/ Hex Artifact Content
Login

Artifact ca8b7b6329937e54a2cce2b897c3a4fa2ec5b3fb:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f  iled mutexing co
1be0: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1bf0: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1c00: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1c10: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1c20: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1c30: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1c40: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1c50: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1c60: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1c70: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1c80: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1c90: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1ca0: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1cb0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
1cc0: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
1cd0: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
1ce0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
1cf0: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
1d00: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
1d10: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
1d20: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
1d30: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
1d40: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
1d50: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
1d60: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
1d70: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
1d80: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
1d90: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
1da0: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
1db0: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
1dc0: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
1dd0: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
1de0: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
1df0: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
1e00: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
1e10: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
1e20: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
1e30: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
1e40: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
1e50: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
1e60: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
1e70: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
1e80: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
1e90: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
1ea0: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
1eb0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
1ec0: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
1ed0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
1ee0: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
1ef0: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
1f00: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
1f10: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
1f20: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
1f30: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1f40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
1f50: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
1f60: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
1f70: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
1f80: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
1f90: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fa0: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
1fb0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1fc0: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
1fd0: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
1fe0: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
1ff0: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2000: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2010: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
2020: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
2030: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
2040: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
2050: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
2060: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
2070: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2080: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
2090: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
20a0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
20b0: 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e  ONFIG_MUTEX].  ^
20c0: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
20d0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
20e0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
20f0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2100: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
2110: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
2120: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
2130: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
2140: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
2150: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
2160: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
2170: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
2180: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2190: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
21a0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
21b0: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
21c0: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
21d0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
21e0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
21f0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2200: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
2210: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
2230: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
2240: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
2250: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2260: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2270: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2280: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2290: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
22a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
22c0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
22d0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
22e0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
22f0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2300: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
2310: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
2320: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
2330: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
2340: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
2350: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
2360: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2370: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2380: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2390: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
23a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
23b0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
23c0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
23d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
23e0: 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20  se()].** is its 
23f0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
2400: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2410: 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75  r interfaces (su
2420: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  ch as.** [sqlite
2430: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2450: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
2460: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
2470: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
2480: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
2490: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
24a0: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  s on an.** sqlit
24b0: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  e3 object..*/.ty
24c0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
24d0: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f  ite3 sqlite3;../
24e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36  *.** CAPI3REF: 6
24f0: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79  4-Bit Integer Ty
2500: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2510: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
2520: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
2530: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
2540: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
2550: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
2560: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
2570: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
2580: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
2590: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
25a0: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
25b0: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
25c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25d0: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
25e0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
25f0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
2600: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
2610: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
2620: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2630: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
2640: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
2650: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
2660: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
2670: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
2680: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
2690: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
26a0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
26b0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
26c0: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  -922337203685477
26d0: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37  5808 and +922337
26e0: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e  2036854775807 in
26f0: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a  clusive.  ^The.*
2700: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  * sqlite3_uint64
2710: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2720: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f  64 types can sto
2730: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  re integer value
2740: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  s .** between 0 
2750: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33  and +18446744073
2760: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73  709551615 inclus
2770: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ive..*/.#ifdef S
2780: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2790: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54  .  typedef SQLIT
27a0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
27b0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
27c0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51  edef unsigned SQ
27d0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
27f0: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
2800: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65  C_VER) || define
2810: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
2820: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36    typedef __int6
2830: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  4 sqlite_int64;.
2840: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2850: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ed __int64 sqlit
2860: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a  e_uint64;.#else.
2870: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c    typedef long l
2880: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69  ong int sqlite_i
2890: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
28a0: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f  unsigned long lo
28b0: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69  ng int sqlite_ui
28c0: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70  nt64;.#endif.typ
28d0: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36  edef sqlite_int6
28e0: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b  4 sqlite3_int64;
28f0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2900: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  uint64 sqlite3_u
2910: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66  int64;../*.** If
2920: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61   compiling for a
2930: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20   processor that 
2940: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70  lacks floating p
2950: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a  oint support,.**
2960: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65   substitute inte
2970: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67  ger for floating
2980: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65  -point..*/.#ifde
2990: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
29a0: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
29b0: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
29c0: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
29d0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
29e0: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
29f0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2a00: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a10: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74  te3_close() rout
2a20: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
2a30: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
2a40: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
2a50: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
2a60: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74  ite3_close() ret
2a70: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
2a80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2a90: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63  bject is.** succ
2aa0: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79  essfully destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62  not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72       the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69   running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66  n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20  ent text passed 
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65  into.**      the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
3e40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e50: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3e60: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3e70: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3e80: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3e90: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ea0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3eb0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3ec0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3ed0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3ef0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f00: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f10: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f30: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f40: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f50: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f70: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3f80: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3f90: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fa0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3fb0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
3fc0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
3fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3fe0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
3ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4000: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4010: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4020: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4030: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4040: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4050: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4060: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4080: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4090: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40a0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
40c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
40d0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
40e0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
40f0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4100: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4110: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4120: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4130: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4140: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4160: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4170: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4180: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4190: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41b0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
41c0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c  * NOT USED. Tabl
41d0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20  e or record not 
41e0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65  found */.#define
41f0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
4200: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
4210: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
4220: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
4230: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
4240: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
4250: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
4260: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
4270: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4290: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
42a0: 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b  /* Database lock
42b0: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20   protocol error 
42c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
42d0: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36  E_EMPTY       16
42e0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69     /* Database i
42f0: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69  s empty */.#defi
4300: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  ne SQLITE_SCHEMA
4310: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68        17   /* Th
4320: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
4330: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65  a changed */.#de
4340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42  fine SQLITE_TOOB
4350: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20  IG      18   /* 
4360: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65  String or BLOB e
4370: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69  xceeds size limi
4380: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4390: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20  ITE_CONSTRAINT  
43a0: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75  19   /* Abort du
43b0: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20  e to constraint 
43c0: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65  violation */.#de
43d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d  fine SQLITE_MISM
43e0: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20  ATCH    20   /* 
43f0: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74  Data type mismat
4400: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ch */.#define SQ
4410: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20  LITE_MISUSE     
4420: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79   21   /* Library
4430: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c   used incorrectl
4440: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4450: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20  ITE_NOLFS       
4460: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20  22   /* Uses OS 
4470: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70  features not sup
4480: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a  ported on host *
4490: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44a0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20  _AUTH        23 
44b0: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69    /* Authorizati
44c0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
44d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d  fine SQLITE_FORM
44e0: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20  AT      24   /* 
44f0: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61  Auxiliary databa
4500: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20  se format error 
4510: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4520: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35  E_RANGE       25
4530: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65     /* 2nd parame
4540: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
4550: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65  ind out of range
4560: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4570: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32  TE_NOTADB      2
4580: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e  6   /* File open
4590: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61  ed that is not a
45a0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
45b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45c0: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
45d0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
45e0: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20  p() has another 
45f0: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65  row ready */.#de
4600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45  fine SQLITE_DONE
4610: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20          101  /* 
4620: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4630: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
4640: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d  uting */./* end-
4650: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
4660: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
4670: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  F: Extended Resu
4680: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4690: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
46a0: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74  error code} {ext
46b0: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
46c0: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
46d0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
46e0: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
46f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a   result codes}.*
4700: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4710: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4720: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4730: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4740: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a  e of 26 integer.
4750: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
4760: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20  result codes].  
4770: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65  However, experie
4780: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68  nce has shown th
4790: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68  at many of.** th
47a0: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ese result codes
47b0: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d   are too coarse-
47c0: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64  grained.  They d
47d0: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73  o not provide as
47e0: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61  .** much informa
47f0: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c  tion about probl
4800: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65  ems as programme
4810: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20  rs might like.  
4820: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a  In an effort to.
4830: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c  ** address this,
4840: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
4850: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69  of SQLite (versi
4860: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74  on 3.3.8 and lat
4870: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73  er) include.** s
4880: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74  upport for addit
4890: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64  ional result cod
48a0: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20  es that provide 
48b0: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e  more detailed in
48c0: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
48d0: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65  ut errors. The e
48e0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
48f0: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  odes are enabled
4900: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4910: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4920: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4930: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4940: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4950: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4960: 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  ] API..**.** Som
4970: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62  e of the availab
4980: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  le extended resu
4990: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73  lt codes are lis
49a0: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65  ted here..** One
49b0: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20   may expect the 
49c0: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
49d0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
49e0: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
49f0: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
4a00: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
4a10: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4a20: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
4a30: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
4a40: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
4a50: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
4a60: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
4a70: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
4a80: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
4a90: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
4aa0: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
4ab0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
4ac0: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65  tly zero..*/.#de
4ad0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ae0: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
4af0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4b00: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
4b10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4b20: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
4b30: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4b40: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
4b50: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4b60: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
4b70: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4b80: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
4b90: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
4ba0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
4bb0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4bc0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
4bd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4be0: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
4bf0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4c00: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
4c10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
4c20: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
4c30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4c40: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
4c50: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
4c60: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
4c70: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
4c80: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4c90: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
4ca0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
4cb0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
4cc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4cd0: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
4ce0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4cf0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
4d00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d10: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
4d20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
4d40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d50: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
4d60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
4d80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d90: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
4da0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4db0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
4dc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4dd0: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
4de0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4df0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
4e00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e10: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
4e20: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
4e30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
4e40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e50: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
4e60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4e70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
4e80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e90: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
4ea0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4eb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
4ec0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ed0: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
4ee0: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
4ef0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
4f00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f10: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e  TE_IOERR_SHMOPEN
4f20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c  TE_IOERR | (18<<
4f40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f50: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45  TE_IOERR_SHMSIZE
4f60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c  TE_IOERR | (19<<
4f80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f90: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b  TE_IOERR_SHMLOCK
4fa0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4fb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c  TE_IOERR | (20<<
4fc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4fd0: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
4fe0: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
4ff0: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c  TE_LOCKED |  (1<
5000: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5010: 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52  ITE_BUSY_RECOVER
5020: 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  Y           (SQL
5030: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31  ITE_BUSY   |  (1
5040: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5050: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f  LITE_CANTOPEN_NO
5060: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51  TEMPDIR      (SQ
5070: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5080: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
5090: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
50a0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
50b0: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
50c0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
50d0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
50e0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
50f0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
5100: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
5110: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5120: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5130: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
5140: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
5150: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
5160: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
5170: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5180: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
5190: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
51a0: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
51b0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
51c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
51d0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
51e0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
51f0: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
5200: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5210: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5220: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
5230: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5240: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
5250: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5260: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5270: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
5280: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
5290: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
52a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52b0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
52c0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
52d0: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
52e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52f0: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
5300: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
5310: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
5320: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5330: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
5340: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5350: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
5360: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5370: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
5380: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5390: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
53a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53b0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
53c0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
53d0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
53e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53f0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
5400: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
5410: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
5420: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5430: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
5440: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
5450: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
5460: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5470: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
5480: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
5490: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54b0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
54c0: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
54d0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54f0: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
5500: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
5510: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5520: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5530: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5540: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
5550: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
5560: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5570: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5580: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5590: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
55a0: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
55b0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
55c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
55d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
55e0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
55f0: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
5600: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5610: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5620: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5630: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
5640: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
5650: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
5660: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
5670: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
5680: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
5690: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61  * The xDeviceCha
56a0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
56b0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
56c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
56d0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
56e0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
56f0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
5700: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
5710: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
5720: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
5730: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
5740: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
5750: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
5760: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
5770: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
5780: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
5790: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
57a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
57b0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
57c0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
57d0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
57e0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
57f0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5800: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
5810: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
5820: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
5830: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
5840: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
5850: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
5860: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
5870: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
5880: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
5890: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
58a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
58b0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
58c0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
58d0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
58e0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
58f0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
5900: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
5910: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
5920: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
5930: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
5940: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
5950: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
5960: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5970: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
5980: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
5990: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
59a0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
59b0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
59c0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
59d0: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
59e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
59f0: 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  IC              
5a00: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
5a10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5a20: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20  AP_ATOMIC512    
5a30: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5a40: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
5a50: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5a60: 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  1K              
5a70: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
5a80: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5a90: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
5aa0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5ab0: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
5ac0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
5ad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5ae0: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e  x00000010.#defin
5af0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5b00: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20  TOMIC8K         
5b10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
5b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5b50: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
5b60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b70: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20  MIC32K          
5b80: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23      0x00000080.#
5b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5ba0: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20  CAP_ATOMIC64K   
5bb0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5bc0: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
5bd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
5be0: 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20  APPEND          
5bf0: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
5c00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5c10: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20  P_SEQUENTIAL    
5c20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5c30: 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  400.#define SQLI
5c40: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
5c50: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20  ABLE_WHEN_OPEN  
5c60: 30 78 30 30 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a  0x00000800../*.*
5c70: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
5c80: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
5c90: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
5ca0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
5cb0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
5cc0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
5cd0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
5ce0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
5cf0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
5d00: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
5d10: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
5d20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5d30: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
5d40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5d50: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
5d60: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5d70: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
5d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5d90: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
5da0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
5db0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
5dc0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
5dd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5de0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
5df0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
5e00: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
5e10: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
5e20: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
5e30: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
5e40: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
5e50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5e60: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
5e70: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
5e80: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
5e90: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ea0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
5eb0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
5ec0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5ed0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
5ee0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
5ef0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
5f00: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5f10: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5f20: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5f30: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
5f40: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
5f50: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
5f60: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
5f70: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
5f80: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
5f90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
5fa0: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
5fb0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
5fc0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
5fd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
5fe0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
5ff0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
6000: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
6010: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
6020: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
6030: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a   of fsync()..**.
6040: 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73  ** Do not confus
6050: 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  e the SQLITE_SYN
6060: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
6070: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
6080: 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ags.** with the 
6090: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
60a0: 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20  ous]=NORMAL and 
60b0: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
60c0: 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74  ous]=FULL.** set
60d0: 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e  tings.  The [syn
60e0: 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d  chronous pragma]
60f0: 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e   determines when
6100: 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
6110: 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f   xSync VFS metho
6120: 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c  d occur and appl
6130: 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63  ies uniformly ac
6140: 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72  ross all platfor
6150: 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  ms..** The SQLIT
6160: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
6170: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
6180: 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69  LL flags determi
6190: 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65  ne how.** energe
61a0: 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20  tic or rigorous 
61b0: 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20  or forceful the 
61c0: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20  sync operations 
61d0: 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20  are and.** only 
61e0: 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63  make a differenc
61f0: 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72  e on Mac OSX for
6200: 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c   the default SQL
6210: 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68  ite code..** (Th
6220: 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d  ird-party VFS im
6230: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69  plementations mi
6240: 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68  ght also make th
6250: 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a  e distinction.**
6260: 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f   between SQLITE_
6270: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
6280: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
6290: 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a  , but among the.
62a0: 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ** operating sys
62b0: 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75  tems natively su
62c0: 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
62d0: 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a  e, only Mac OSX.
62e0: 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74  ** cares about t
62f0: 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a  he difference.).
6300: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6310: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20  E_SYNC_NORMAL   
6320: 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65       0x00002.#de
6330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
6340: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30  _FULL          0
6350: 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53  x00003.#define S
6360: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
6370: 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30  NLY      0x00010
6380: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6390: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
63a0: 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a  pen File Handle.
63b0: 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65  **.** An [sqlite
63c0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72  3_file] object r
63d0: 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65  epresents an ope
63e0: 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a  n file in the .*
63f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  * [sqlite3_vfs |
6400: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
6410: 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61  yer].  Individua
6420: 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a  l OS interface.*
6430: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
6440: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74  s will.** want t
6450: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20  o subclass this 
6460: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64  object by append
6470: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ing additional f
6480: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ields.** for the
6490: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65  ir own use.  The
64a0: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20   pMethods entry 
64b0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
64c0: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
64d0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
64e0: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d  t that defines m
64f0: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f  ethods for perfo
6500: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65  rming.** I/O ope
6510: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f  rations on the o
6520: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70  pen file..*/.typ
6530: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
6540: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33  te3_file sqlite3
6550: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71  _file;.struct sq
6560: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63  lite3_file {.  c
6570: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
6580: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a  te3_io_methods *
6590: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65  pMethods;  /* Me
65a0: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65  thods for an ope
65b0: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  n file */.};../*
65c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
65d0: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20   Interface File 
65e0: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20  Virtual Methods 
65f0: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65  Object.**.** Eve
6600: 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62  ry file opened b
6610: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  y the [sqlite3_v
6620: 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  fs] xOpen method
6630: 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a   populates an.**
6640: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
6650: 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65  object (or, more
6660: 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62   commonly, a sub
6670: 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20  class of the.** 
6680: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
6690: 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f  bject) with a po
66a0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
66b0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
66c0: 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ect..** This obj
66d0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
66e0: 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20  methods used to 
66f0: 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
6700: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67  operations.** ag
6710: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66  ainst the open f
6720: 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20  ile represented 
6730: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
6740: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  file] object..**
6750: 0a 2a 2a 20 49 66 20 74 68 65 20 78 4f 70 65 6e  .** If the xOpen
6760: 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65   method sets the
6770: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
6780: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a  ethods element .
6790: 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ** to a non-NULL
67a0: 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74   pointer, then t
67b0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  he sqlite3_io_me
67c0: 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74  thods.xClose met
67d0: 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e  hod.** may be in
67e0: 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68  voked even if th
67f0: 65 20 78 4f 70 65 6e 20 72 65 70 6f 72 74 65 64  e xOpen reported
6800: 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e   that it failed.
6810: 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61    The.** only wa
6820: 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63  y to prevent a c
6830: 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f  all to xClose fo
6840: 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64  llowing a failed
6850: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72   xOpen.** is for
6860: 20 74 68 65 20 78 4f 70 65 6e 20 74 6f 20 73 65   the xOpen to se
6870: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
6880: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d  le.pMethods elem
6890: 65 6e 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ent to NULL..**.
68a0: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
68b0: 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d  ument to xSync m
68c0: 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51  ay be one of [SQ
68d0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
68e0: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
68f0: 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65  SYNC_FULL].  The
6900: 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73   first choice is
6910: 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   the normal fsyn
6920: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  c()..** The seco
6930: 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d  nd choice is a M
6940: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
6950: 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51  llsync.  The [SQ
6960: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
6970: 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20  LY].** flag may 
6980: 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e  be ORed in to in
6990: 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79  dicate that only
69a0: 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65   the data of the
69b0: 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74   file.** and not
69c0: 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73   its inode needs
69d0: 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a   to be synced..*
69e0: 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72  *.** The integer
69f0: 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b   values to xLock
6a00: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
6a10: 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c   are one of.** <
6a20: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
6a30: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a  ITE_LOCK_NONE],.
6a40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6a50: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
6a60: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
6a70: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a  CK_RESERVED],.**
6a80: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
6a90: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a  CK_PENDING], or.
6aa0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6ab0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e  LOCK_EXCLUSIVE].
6ac0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f  .** </ul>.** xLo
6ad0: 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74  ck() increases t
6ae0: 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b  he lock. xUnlock
6af0: 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65  () decreases the
6b00: 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43   lock..** The xC
6b10: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
6b20: 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73  () method checks
6b30: 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74   whether any dat
6b40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
6b50: 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74  ,.** either in t
6b60: 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69  his process or i
6b70: 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f  n some other pro
6b80: 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67  cess, is holding
6b90: 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20   a RESERVED,.** 
6ba0: 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c  PENDING, or EXCL
6bb0: 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68  USIVE lock on th
6bc0: 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75  e file.  It retu
6bd0: 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73  rns true.** if s
6be0: 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74  uch a lock exist
6bf0: 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65  s and false othe
6c00: 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rwise..**.** The
6c10: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
6c20: 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65  method is a gene
6c30: 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68  ric interface th
6c40: 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d  at allows custom
6c50: 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  .** VFS implemen
6c60: 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63  tations to direc
6c70: 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f  tly control an o
6c80: 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74  pen file using t
6c90: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
6ca0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69  ile_control()] i
6cb0: 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73  nterface.  The s
6cc0: 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d  econd "op" argum
6cd0: 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74  ent is an.** int
6ce0: 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68  eger opcode.  Th
6cf0: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
6d00: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f   is a generic po
6d10: 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74  inter intended t
6d20: 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20  o.** point to a 
6d30: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d  structure that m
6d40: 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d  ay contain argum
6d50: 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e  ents or space in
6d60: 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69   which to.** wri
6d70: 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73  te return values
6d80: 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65  .  Potential use
6d90: 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72  s for xFileContr
6da0: 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a  ol() might be.**
6db0: 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e   functions to en
6dc0: 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f  able blocking lo
6dd0: 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74  cks with timeout
6de0: 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  s, to change the
6df0: 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61  .** locking stra
6e00: 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c  tegy (for exampl
6e10: 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c  e to use dot-fil
6e20: 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71  e locks), to inq
6e30: 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68  uire.** about th
6e40: 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f  e status of a lo
6e50: 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20  ck, or to break 
6e60: 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68  stale locks.  Th
6e70: 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65  e SQLite.** core
6e80: 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70   reserves all op
6e90: 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20  codes less than 
6ea0: 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20  100 for its own 
6eb0: 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54  use..** A [SQLIT
6ec0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
6ed0: 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f  E | list of opco
6ee0: 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31  des] less than 1
6ef0: 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  00 is available.
6f00: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
6f10: 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63   that define a c
6f20: 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72  ustom xFileContr
6f30: 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  ol method should
6f40: 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20   use opcodes.** 
6f50: 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30  greater than 100
6f60: 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69   to avoid confli
6f70: 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  cts..**.** The x
6f80: 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74  SectorSize() met
6f90: 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20  hod returns the 
6fa0: 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74  sector size of t
6fb0: 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  he.** device tha
6fc0: 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20  t underlies the 
6fd0: 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f  file.  The secto
6fe0: 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a  r size is the.**
6ff0: 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74   minimum write t
7000: 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f  hat can be perfo
7010: 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73  rmed without dis
7020: 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  turbing.** other
7030: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
7040: 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65  le.  The xDevice
7050: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28  Characteristics(
7060: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
7070: 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72  rns a bit vector
7080: 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61   describing beha
7090: 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20  viors of the.** 
70a0: 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63  underlying devic
70b0: 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
70c0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
70d0: 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c  CAP_ATOMIC].** <
70e0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
70f0: 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20  P_ATOMIC512].** 
7100: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7110: 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20  AP_ATOMIC1K].** 
7120: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7130: 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20  AP_ATOMIC2K].** 
7140: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7150: 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20  AP_ATOMIC4K].** 
7160: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7170: 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20  AP_ATOMIC8K].** 
7180: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7190: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a  AP_ATOMIC16K].**
71a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
71b0: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a  CAP_ATOMIC32K].*
71c0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
71d0: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a  OCAP_ATOMIC64K].
71e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
71f0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
7200: 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  D].** <li> [SQLI
7210: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
7220: 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IAL].** </ul>.**
7230: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
7240: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
7250: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
7260: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
7270: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
7280: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
7290: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
72a0: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
72b0: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
72c0: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
72d0: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
72e0: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
72f0: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
7300: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
7310: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
7320: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
7330: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
7340: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
7350: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
7360: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
7370: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
7380: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
7390: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
73a0: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
73b0: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
73c0: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
73d0: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
73e0: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
73f0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
7400: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
7410: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
7420: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
7430: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
7440: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
7450: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
7460: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a   xWrite()..**.**
7470: 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75   If xRead() retu
7480: 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  rns SQLITE_IOERR
7490: 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d  _SHORT_READ it m
74a0: 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a  ust also fill.**
74b0: 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70   in the unread p
74c0: 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62  ortions of the b
74d0: 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73  uffer with zeros
74e0: 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a  .  A VFS that.**
74f0: 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66   fails to zero-f
7500: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20  ill short reads 
7510: 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f  might seem to wo
7520: 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  rk.  However,.**
7530: 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f   failure to zero
7540: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
7550: 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c  s will eventuall
7560: 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74  y lead to.** dat
7570: 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e  abase corruption
7580: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
7590: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
75a0: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69  ethods sqlite3_i
75b0: 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  o_methods;.struc
75c0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
75d0: 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  hods {.  int iVe
75e0: 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78  rsion;.  int (*x
75f0: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66  Close)(sqlite3_f
7600: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
7610: 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69  Read)(sqlite3_fi
7620: 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20  le*, void*, int 
7630: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
7640: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
7650: 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69  t (*xWrite)(sqli
7660: 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74  te3_file*, const
7670: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
7680: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
7690: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
76a0: 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74  xTruncate)(sqlit
76b0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
76c0: 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20  3_int64 size);. 
76d0: 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
76e0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
76f0: 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28   flags);.  int (
7700: 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69  *xFileSize)(sqli
7710: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
7720: 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29  e3_int64 *pSize)
7730: 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29  ;.  int (*xLock)
7740: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7750: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  int);.  int (*xU
7760: 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  nlock)(sqlite3_f
7770: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
7780: 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76  t (*xCheckReserv
7790: 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  edLock)(sqlite3_
77a0: 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73  file*, int *pRes
77b0: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
77c0: 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69  ileControl)(sqli
77d0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
77e0: 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a  p, void *pArg);.
77f0: 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53    int (*xSectorS
7800: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
7810: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  e*);.  int (*xDe
7820: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
7830: 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ics)(sqlite3_fil
7840: 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  e*);.  /* Method
7850: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
7860: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20  d for version 1 
7870: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d  */.  int (*xShmM
7880: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ap)(sqlite3_file
7890: 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20  *, int iPg, int 
78a0: 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20  pgsz, int, void 
78b0: 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69  volatile**);.  i
78c0: 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73  nt (*xShmLock)(s
78d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
78e0: 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c  t offset, int n,
78f0: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76   int flags);.  v
7900: 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65  oid (*xShmBarrie
7910: 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  r)(sqlite3_file*
7920: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55  );.  int (*xShmU
7930: 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  nmap)(sqlite3_fi
7940: 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46  le*, int deleteF
7950: 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  lag);.  /* Metho
7960: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
7970: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32  id for version 2
7980: 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f   */.  /* Additio
7990: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20  nal methods may 
79a0: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
79b0: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d  re releases */.}
79c0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
79d0: 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65  F: Standard File
79e0: 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73   Control Opcodes
79f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
7a00: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61  eger constants a
7a10: 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74  re opcodes for t
7a20: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
7a30: 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65  method.** of the
7a40: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
7a50: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64  hods] object and
7a60: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
7a70: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
7a80: 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a  ].** interface..
7a90: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
7aa0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
7ab0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
7ac0: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
7ad0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
7ae0: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
7af0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
7b00: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
7b10: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
7b20: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
7b30: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
7b40: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
7b50: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
7b60: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
7b70: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
7b80: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
7b90: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
7ba0: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
7bb0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
7bc0: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
7bd0: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
7be0: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
7bf0: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
7c00: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c   testing and onl
7c10: 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75  y needs to be su
7c20: 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c  pported when SQL
7c30: 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64  ITE_TEST.** is d
7c40: 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
7c50: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
7c60: 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64  SIZE_HINT] opcod
7c70: 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c  e is used by SQL
7c80: 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20  ite to give the 
7c90: 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68  VFS.** layer a h
7ca0: 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65  int of how large
7cb0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
7cc0: 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20  le will grow to 
7cd0: 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a  be during the.**
7ce0: 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63   current transac
7cf0: 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74  tion.  This hint
7d00: 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65   is not guarante
7d10: 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74  ed to be accurat
7d20: 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f  e but it.** is o
7d30: 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65  ften close.  The
7d40: 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20   underlying VFS 
7d50: 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20  might choose to 
7d60: 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61  preallocate data
7d70: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61  base.** file spa
7d80: 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73  ce based on this
7d90: 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74   hint in order t
7da0: 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f  o help writes to
7db0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
7dc0: 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72   file run faster
7dd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
7de0: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
7df0: 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  SIZE] opcode is 
7e00: 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20  used to request 
7e10: 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20  that the VFS.** 
7e20: 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e  extends and trun
7e30: 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61  cates the databa
7e40: 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b  se file in chunk
7e50: 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63  s of a size spec
7e60: 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
7e70: 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68  user. The fourth
7e80: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
7e90: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
7ea0: 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a  ol()] should .**
7eb0: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74   point to an int
7ec0: 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20  eger (type int) 
7ed0: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
7ee0: 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f  ew chunk-size to
7ef0: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20   use.** for the 
7f00: 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61  nominated databa
7f10: 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64  se. Allocating d
7f20: 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61  atabase file spa
7f30: 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63  ce in large.** c
7f40: 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61  hunks (say 1MB a
7f50: 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72  t a time), may r
7f60: 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65  educe file-syste
7f70: 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20  m fragmentation 
7f80: 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70  and.** improve p
7f90: 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f  erformance on so
7fa0: 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a  me systems..**.*
7fb0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
7fc0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
7fd0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
7fe0: 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69   to obtain a poi
7ff0: 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
8000: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
8010: 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20  ject associated 
8020: 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
8030: 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  r database.** co
8040: 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74  nnection.  See t
8050: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
8060: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75  _control()] docu
8070: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
8080: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
8090: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
80a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
80b0: 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73  _SYNC] opcode is
80c0: 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
80d0: 2e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 0a 2a  . SQLite calls.*
80e0: 2a 20 74 68 65 20 66 69 6c 65 2d 63 6f 6e 74 72  * the file-contr
80f0: 6f 6c 20 6d 65 74 68 6f 64 20 77 69 74 68 20 74  ol method with t
8100: 68 69 73 20 6f 70 63 6f 64 65 20 69 6d 6d 65 64  his opcode immed
8110: 69 61 74 65 6c 79 20 61 66 74 65 72 20 74 68 65  iately after the
8120: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
8130: 65 20 69 73 20 73 79 6e 63 65 64 2c 20 6f 72 20  e is synced, or 
8140: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
8150: 69 73 20 72 75 6e 6e 69 6e 67 20 69 6e 20 73 79  is running in sy
8160: 6e 63 68 72 6f 6e 6f 75 73 3d 6f 66 66 20 6d 6f  nchronous=off mo
8170: 64 65 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  de.** immediatel
8180: 79 20 61 66 74 65 72 20 69 74 20 77 6f 75 6c 64  y after it would
8190: 20 68 61 76 65 20 62 65 65 6e 20 73 79 6e 63 65   have been synce
81a0: 64 20 6f 74 68 65 72 77 69 73 65 2e 20 54 68 69  d otherwise. Thi
81b0: 73 20 6d 61 6b 65 73 20 69 74 0a 2a 2a 20 65 61  s makes it.** ea
81c0: 73 69 65 72 20 74 6f 20 77 72 69 74 65 20 73 70  sier to write sp
81d0: 65 63 69 61 6c 20 56 46 53 20 6d 6f 64 75 6c 65  ecial VFS module
81e0: 73 20 74 68 61 74 20 64 65 70 65 6e 64 20 6f 6e  s that depend on
81f0: 20 74 68 65 20 78 53 79 6e 63 20 63 61 6c 6c 2e   the xSync call.
8200: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
8210: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
8220: 54 45 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  TE        1.#def
8230: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c  ine SQLITE_GET_L
8240: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
8250: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
8260: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_SET_LOCKPROXY
8270: 46 49 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66  FILE      3.#def
8280: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f  ine SQLITE_LAST_
8290: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
82a0: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
82b0: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
82c0: 4e 54 20 20 20 20 20 20 20 20 35 0a 23 64 65 66  NT        5.#def
82d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
82e0: 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20  _CHUNK_SIZE     
82f0: 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
8300: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
8310: 49 4e 54 45 52 20 20 20 20 20 37 0a 23 64 65 66  INTER     7.#def
8320: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
8330: 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20  _SYNC           
8340: 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
8350: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
8360: 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74  le.**.** The mut
8370: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e  ex module within
8380: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20   SQLite defines 
8390: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
83a0: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74  to be an.** abst
83b0: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20  ract type for a 
83c0: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54  mutex object.  T
83d0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e  he SQLite core n
83e0: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74  ever looks.** at
83f0: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
8400: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
8410: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  an [sqlite3_mute
8420: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20  x].  It only.** 
8430: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74  deals with point
8440: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ers to the [sqli
8450: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
8460: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73  t..**.** Mutexes
8470: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
8480: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
8490: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74  x_alloc()]..*/.t
84a0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
84b0: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69  lite3_mutex sqli
84c0: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a  te3_mutex;../*.*
84d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
84e0: 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a  nterface Object.
84f0: 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
8500: 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  e of the sqlite3
8510: 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69  _vfs object defi
8520: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
8530: 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  e between.** the
8540: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64   SQLite core and
8550: 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
8560: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
8570: 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20  .  The "vfs".** 
8580: 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  in the name of t
8590: 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73  he object stands
85a0: 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69   for "virtual fi
85b0: 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a  le system"..**.*
85c0: 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * The value of t
85d0: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
85e0: 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31  d is initially 1
85f0: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
8600: 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20  er in.** future 
8610: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
8620: 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  te.  Additional 
8630: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
8640: 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a  pended to this.*
8650: 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68  * object when th
8660: 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65  e iVersion value
8670: 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20   is increased.  
8680: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74  Note that the st
8690: 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68  ructure.** of th
86a0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
86b0: 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20  ject changes in 
86c0: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
86d0: 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74  between.** SQLit
86e0: 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20  e version 3.5.9 
86f0: 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65  and 3.6.0 and ye
8700: 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  t the iVersion f
8710: 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20  ield was not.** 
8720: 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  modified..**.** 
8730: 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65  The szOsFile fie
8740: 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f  ld is the size o
8750: 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64  f the subclassed
8760: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a   [sqlite3_file].
8770: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65  ** structure use
8780: 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20  d by this VFS.  
8790: 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68  mxPathname is th
87a0: 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
87b0: 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d   of.** a pathnam
87c0: 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a  e in this VFS..*
87d0: 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20  *.** Registered 
87e0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
87f0: 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20  cts are kept on 
8800: 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f  a linked list fo
8810: 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70  rmed by.** the p
8820: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54  Next pointer.  T
8830: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
8840: 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61  register()].** a
8850: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  nd [sqlite3_vfs_
8860: 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e  unregister()] in
8870: 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20  terfaces manage 
8880: 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20  this list.** in 
8890: 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61  a thread-safe wa
88a0: 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  y.  The [sqlite3
88b0: 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74  _vfs_find()] int
88c0: 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68  erface.** search
88d0: 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65  es the list.  Ne
88e0: 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63  ither the applic
88f0: 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74  ation code nor t
8900: 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d  he VFS.** implem
8910: 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
8920: 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f  use the pNext po
8930: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
8940: 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20   pNext field is 
8950: 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69  the only field i
8960: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
8970: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74  s.** structure t
8980: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
8990: 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51  ever modify.  SQ
89a0: 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61  Lite will only a
89b0: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69  ccess.** or modi
89c0: 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68  fy this field wh
89d0: 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61  ile holding a pa
89e0: 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20  rticular static 
89f0: 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70  mutex..** The ap
8a00: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
8a10: 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e   never modify an
8a20: 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68  ything within th
8a30: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
8a40: 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65   object once the
8a50: 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e   object has been
8a60: 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a   registered..**.
8a70: 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65  ** The zName fie
8a80: 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d  ld holds the nam
8a90: 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64  e of the VFS mod
8aa0: 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d  ule.  The name m
8ab0: 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65  ust.** be unique
8ac0: 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20   across all VFS 
8ad0: 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  modules..**.** ^
8ae0: 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
8af0: 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65  s that the zFile
8b00: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74  name parameter t
8b10: 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69  o xOpen.** is ei
8b20: 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ther a NULL poin
8b30: 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62  ter or string ob
8b40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78  tained.** from x
8b50: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77  FullPathname() w
8b60: 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20  ith an optional 
8b70: 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a  suffix added..**
8b80: 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73   ^If a suffix is
8b90: 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46   added to the zF
8ba0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
8bb0: 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f  r, it will.** co
8bc0: 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c  nsist of a singl
8bd0: 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20  e "-" character 
8be0: 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d  followed by no m
8bf0: 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 30 20 61  ore than.** 10 a
8c00: 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f  lphanumeric and/
8c10: 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  or "-" character
8c20: 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75  s..** ^SQLite fu
8c30: 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73  rther guarantees
8c40: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72   that.** the str
8c50: 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ing will be vali
8c60: 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20  d and unchanged 
8c70: 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69  until xClose() i
8c80: 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63  s.** called. Bec
8c90: 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76  ause of the prev
8ca0: 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a  ious sentence,.*
8cb0: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  * the [sqlite3_f
8cc0: 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20  ile] can safely 
8cd0: 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20  store a pointer 
8ce0: 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61  to the.** filena
8cf0: 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74  me if it needs t
8d00: 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66  o remember the f
8d10: 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65  ilename for some
8d20: 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74   reason..** If t
8d30: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
8d40: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20  ameter to xOpen 
8d50: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
8d60: 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20  r then xOpen.** 
8d70: 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20  must invent its 
8d80: 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61  own temporary na
8d90: 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e  me for the file.
8da0: 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20    ^Whenever the 
8db0: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
8dc0: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
8dd0: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
8de0: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
8df0: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
8e00: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
8e10: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
8e20: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
8e30: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
8e40: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
8e50: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
8e60: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
8e70: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
8e80: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
8e90: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
8ea0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
8eb0: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
8ec0: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
8ed0: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
8ee0: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
8ef0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
8f00: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
8f10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
8f20: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
8f30: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
8f40: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
8f50: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
8f60: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
8f70: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
8f80: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
8f90: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
8fa0: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
8fb0: 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c  .** ^(SQLite wil
8fc0: 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  l also add one o
8fd0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
8fe0: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
8ff0: 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65  en().** call, de
9000: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
9010: 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e  bject being open
9020: 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ed:.**.** <ul>.*
9030: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
9040: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a  OPEN_MAIN_DB].**
9050: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
9060: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
9070: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
9080: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d  TE_OPEN_TEMP_DB]
9090: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
90a0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
90b0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
90c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
90d0: 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  IENT_DB].** <li>
90e0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53    [SQLITE_OPEN_S
90f0: 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  UBJOURNAL].** <l
9100: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
9110: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d  _MASTER_JOURNAL]
9120: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
9130: 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c  E_OPEN_WAL].** <
9140: 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
9150: 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d   file I/O implem
9160: 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65  entation can use
9170: 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65   the object type
9180: 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61   flags to.** cha
9190: 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64  nge the way it d
91a0: 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e  eals with files.
91b0: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61    For example, a
91c0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  n application.**
91d0: 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63   that does not c
91e0: 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20  are about crash 
91f0: 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c  recovery or roll
9200: 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a  back might make.
9210: 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61  ** the open of a
9220: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20   journal file a 
9230: 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74  no-op.  Writes t
9240: 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77  o this journal w
9250: 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20  ould.** also be 
9260: 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20  no-ops, and any 
9270: 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20  attempt to read 
9280: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  the journal woul
9290: 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49  d return.** SQLI
92a0: 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68  TE_IOERR.  Or th
92b0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
92c0: 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65   might recognize
92d0: 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65   that a database
92e0: 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  .** file will be
92f0: 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67   doing page-alig
9300: 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73  ned sector reads
9310: 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61   and writes in a
9320: 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72   random.** order
9330: 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20   and set up its 
9340: 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63  I/O subsystem ac
9350: 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a  cordingly..**.**
9360: 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c   SQLite might al
9370: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
9380: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
9390: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d  s to the xOpen m
93a0: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
93b0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
93c0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
93d0: 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  LOSE].** <li> [S
93e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
93f0: 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  SIVE].** </ul>.*
9400: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
9410: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
9420: 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20  OSE] flag means 
9430: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
9440: 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68  be.** deleted wh
9450: 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e  en it is closed.
9460: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f    ^The [SQLITE_O
9470: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
9480: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
9490: 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62  t for TEMP datab
94a0: 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a  ases and their j
94b0: 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65  ournals, transie
94c0: 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c  nt.** databases,
94d0: 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73   and subjournals
94e0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
94f0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
9500: 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77  IVE] flag is alw
9510: 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a  ays used in conj
9520: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20  unction.** with 
9530: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
9540: 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77  _CREATE] flag, w
9550: 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69  hich are both di
9560: 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67  rectly.** analog
9570: 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43  ous to the O_EXC
9580: 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c  L and O_CREAT fl
9590: 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58  ags of the POSIX
95a0: 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20   open().** API. 
95b0: 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   The SQLITE_OPEN
95c0: 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c  _EXCLUSIVE flag,
95d0: 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74   when paired wit
95e0: 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45  h the .** SQLITE
95f0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73  _OPEN_CREATE, is
9600: 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
9610: 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75  e that file shou
9620: 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ld always.** be 
9630: 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61  created, and tha
9640: 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72  t it is an error
9650: 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65   if it already e
9660: 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20  xists..** It is 
9670: 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20  <i>not</i> used 
9680: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20  to indicate the 
9690: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f  file should be o
96a0: 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78  pened .** for ex
96b0: 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a  clusive access..
96c0: 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20  **.** ^At least 
96d0: 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f  szOsFile bytes o
96e0: 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c  f memory are all
96f0: 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  ocated by SQLite
9700: 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  .** to hold the 
9710: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
9720: 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64  structure passed
9730: 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   as the third.**
9740: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
9750: 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d  en.  The xOpen m
9760: 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68  ethod does not h
9770: 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61  ave to.** alloca
9780: 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65  te the structure
9790: 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74  ; it should just
97a0: 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f   fill it in.  No
97b0: 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78  te that.** the x
97c0: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74  Open method must
97d0: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
97e0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74  _file.pMethods t
97f0: 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61  o either.** a va
9800: 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  lid [sqlite3_io_
9810: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
9820: 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70  or to NULL.  xOp
9830: 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68  en must do.** th
9840: 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  is even if the o
9850: 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69  pen fails.  SQLi
9860: 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20  te expects that 
9870: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
9880: 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65  .pMethods.** ele
9890: 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c  ment will be val
98a0: 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72  id after xOpen r
98b0: 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73  eturns regardles
98c0: 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73  s of the success
98d0: 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f  .** or failure o
98e0: 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c  f the xOpen call
98f0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6c 61  ..**.** ^The fla
9900: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
9910: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
9920: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
9930: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
9940: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
9950: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
9960: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
9970: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
9980: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
9990: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
99a0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
99b0: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
99c0: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
99d0: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
99e0: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
99f0: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
9a00: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
9a10: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
9a20: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77  ^SQLite will alw
9a30: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
9a40: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
9a50: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
9a60: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
9a70: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
9a80: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65    The exact size
9a90: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
9aa0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
9ab0: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
9ac0: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
9ad0: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20  methods. If the 
9ae0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
9af0: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
9b00: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
9b10: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
9b20: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
9b30: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
9b40: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
9b50: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
9b60: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
9b70: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
9b80: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
9b90: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
9ba0: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
9bb0: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
9bc0: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
9bd0: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
9be0: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
9bf0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20  xCurrentTime(), 
9c00: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
9c10: 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72  Int64().** inter
9c20: 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74  faces are not st
9c30: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
9c40: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
9c50: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
9c60: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
9c70: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
9c80: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
9c90: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
9ca0: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
9cb0: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
9cc0: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
9cd0: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
9ce0: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
9cf0: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
9d00: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
9d10: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
9d20: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
9d30: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
9d40: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
9d50: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
9d60: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
9d70: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
9d80: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
9d90: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
9da0: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
9db0: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
9dc0: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
9dd0: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
9de0: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
9df0: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
9e00: 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20  nd time as.** a 
9e10: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
9e20: 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43  alue..** ^The xC
9e30: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
9e40: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
9e50: 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c  , as an integer,
9e60: 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44   the Julian.** D
9e70: 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70  ay Number multip
9e80: 6c 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  led by 86400000 
9e90: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
9ea0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
9eb0: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
9ec0: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
9ed0: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
9ee0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
9ef0: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
9f00: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
9f10: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
9f20: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
9f30: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
9f40: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
9f50: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
9f60: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
9f70: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
9f80: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
9f90: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
9fa0: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
9fb0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
9fc0: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2f   unavailable..*/
9fd0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
9fe0: 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69  sqlite3_vfs sqli
9ff0: 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20  te3_vfs;.struct 
a000: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
a010: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
a020: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
a030: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
a040: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
a050: 32 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  2) */.  int szOs
a060: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
a070: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
a080: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
a090: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
a0a0: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
a0b0: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
a0c0: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
a0d0: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
a0e0: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
a0f0: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
a100: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
a110: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
a120: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
a130: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
a140: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
a150: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
a160: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
a170: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
a180: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
a190: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
a1a0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
a1b0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
a1c0: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
a1d0: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
a1e0: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
a1f0: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
a200: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
a210: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
a220: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
a230: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
a240: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
a250: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
a260: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
a270: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
a280: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
a290: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
a2a0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
a2b0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
a2c0: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
a2d0: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
a2e0: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
a2f0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
a300: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
a310: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
a320: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
a330: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
a340: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
a350: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
a360: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
a370: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
a380: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
a390: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
a3a0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
a3b0: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
a3c0: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
a3d0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
a3e0: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
a3f0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
a400: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
a410: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
a420: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
a430: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
a440: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
a450: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
a460: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
a470: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
a480: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
a490: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
a4a0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
a4b0: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
a4c0: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
a4d0: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
a4e0: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
a4f0: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
a500: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
a510: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
a520: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
a530: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
a540: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
a550: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
a560: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
a570: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
a580: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
a590: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
a5a0: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79  * New fields may
a5b0: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20   be appended in 
a5c0: 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e  figure versions.
a5d0: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20    The iVersion. 
a5e0: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69   ** value will i
a5f0: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65  ncrement wheneve
a600: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20  r this happens. 
a610: 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  .  */.};../*.** 
a620: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
a630: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
a640: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
a650: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
a660: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20  onstants can be 
a670: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  used as the thir
a680: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
a690: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  * the xAccess me
a6a0: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
a6b0: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
a6c0: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65    They determine
a6d0: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  .** what kind of
a6e0: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65   permissions the
a6f0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
a700: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a  is looking for..
a710: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
a720: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68  CCESS_EXISTS, th
a730: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
a740: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b  .** simply check
a750: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
a760: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69  le exists..** Wi
a770: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
a780: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20  _READWRITE, the 
a790: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
a7a0: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
a7b0: 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63   the named direc
a7c0: 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61  tory is both rea
a7d0: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
a7e0: 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20  le.** (in other 
a7f0: 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20  words, if files 
a800: 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65  can be added, re
a810: 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d  moved, and renam
a820: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  ed within.** the
a830: 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20   directory)..** 
a840: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
a850: 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73  S_READWRITE cons
a860: 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c  tant is currentl
a870: 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74  y used only by t
a880: 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72  he.** [temp_stor
a890: 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
a8a0: 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73  ma], though this
a8b0: 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e   could change in
a8c0: 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c   a future.** rel
a8d0: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
a8e0: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
a8f0: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
a900: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
a910: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
a920: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
a930: 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49  dable.  The SQLI
a940: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63  TE_ACCESS_READ c
a950: 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75  onstant is.** cu
a960: 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20  rrently unused, 
a970: 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20  though it might 
a980: 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74  be used in a fut
a990: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
a9a0: 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  * SQLite..*/.#de
a9b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
a9c0: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
a9d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
a9e0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
a9f0: 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52     /* Used by PR
aa00: 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f  AGMA temp_store_
aa10: 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65  directory */.#de
aa20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
aa30: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20  SS_READ      2  
aa40: 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f   /* Unused */../
aa50: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
aa60: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68  lags for the xSh
aa70: 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64  mLock VFS method
aa80: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
aa90: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64  eger constants d
aaa0: 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75  efine the variou
aab0: 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74  s locking operat
aac0: 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20  ions.** allowed 
aad0: 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  by the xShmLock 
aae0: 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74  method of [sqlit
aaf0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20  e3_io_methods]. 
ab00: 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   The.** followin
ab10: 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c  g are the only l
ab20: 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  egal combination
ab30: 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68  s of flags to th
ab40: 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65  e.** xShmLock me
ab50: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
ab60: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
ab70: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
ab80: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
ab90: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
aba0: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
abb0: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
abc0: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
abd0: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
abe0: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
abf0: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
ac00: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
ac10: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
ac20: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68  * </ul>.**.** Wh
ac30: 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68  en unlocking, th
ac40: 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72  e same SHARED or
ac50: 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20   EXCLUSIVE flag 
ac60: 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64  must be supplied
ac70: 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e   as.** was given
ac80: 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f   no the correspo
ac90: 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a  nding lock.  .**
aca0: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
acb0: 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e   method can tran
acc0: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75  sition between u
acd0: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52  nlocked and SHAR
ace0: 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e  ED or.** between
acf0: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58   unlocked and EX
ad00: 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e  CLUSIVE.  It can
ad10: 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  not transition b
ad20: 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a  etween SHARED.**
ad30: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a   and EXCLUSIVE..
ad40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ad50: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20  E_SHM_UNLOCK    
ad60: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
ad70: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20  ITE_SHM_LOCK    
ad80: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
ad90: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
ada0: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
adb0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
adc0: 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a  USIVE    8../*.*
add0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69  * CAPI3REF: Maxi
ade0: 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64  mum xShmLock ind
adf0: 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68  ex.**.** The xSh
ae00: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20  mLock method on 
ae10: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
ae20: 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c  ods] may use val
ae30: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  ues.** between 0
ae40: 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20   and this upper 
ae50: 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66  bound as its "of
ae60: 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a  fset" argument..
ae70: 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
ae80: 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74  re will never at
ae90: 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65  tempt to acquire
aea0: 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a   or release a.**
aeb0: 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66   lock outside of
aec0: 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23   this range.*/.#
aed0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
aee0: 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38  M_NLOCK        8
aef0: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
af00: 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68  F: Initialize Th
af10: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
af20: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
af30: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
af40: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
af50: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
af60: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68  te library.  ^Th
af70: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
af80: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
af90: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
afa0: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
afb0: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
afc0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
afd0: 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20  ize()..** These 
afe0: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73  routines are des
aff0: 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20  igned to aid in 
b000: 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
b010: 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68  zation and.** sh
b020: 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64  utdown on embedd
b030: 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72  ed systems.  Wor
b040: 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61  kstation applica
b050: 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53  tions using.** S
b060: 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64  QLite normally d
b070: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e  o not need to in
b080: 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74  voke either of t
b090: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
b0a0: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
b0b0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
b0c0: 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  e() is an "effec
b0d0: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
b0e0: 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   is.** the first
b0f0: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
b100: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
b110: 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65  voked during the
b120: 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20   lifetime of.** 
b130: 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  the process, or 
b140: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
b150: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
b160: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
b170: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  invoked.** follo
b180: 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73  wing a call to s
b190: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
b1a0: 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66  ).  ^(Only an ef
b1b0: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
b1c0: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
b1d0: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
b1e0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
b1f0: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
b200: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
b210: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
b220: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
b230: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
b240: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
b250: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74   call if it is t
b260: 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c  he first.** call
b270: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
b280: 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65  down() since the
b290: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e   last sqlite3_in
b2a0: 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f  itialize().  ^(O
b2b0: 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74  nly.** an effect
b2c0: 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ive call to sqli
b2d0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64  te3_shutdown() d
b2e0: 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61  oes any deinitia
b2f0: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c  lization..** All
b300: 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c   other valid cal
b310: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ls to sqlite3_sh
b320: 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72  utdown() are har
b330: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
b340: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
b350: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
b360: 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65  nterface is thre
b370: 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69  adsafe, but sqli
b380: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
b390: 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73  * is not.  The s
b3a0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
b3b0: 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74  ) interface must
b3c0: 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
b3d0: 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  from a.** single
b3e0: 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70   thread.  All op
b3f0: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
b400: 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62  nections] must b
b410: 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c  e closed and all
b420: 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65  .** other SQLite
b430: 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20   resources must 
b440: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70  be deallocated p
b450: 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67  rior to invoking
b460: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74  .** sqlite3_shut
b470: 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d  down()..**.** Am
b480: 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73  ong other things
b490: 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  , ^sqlite3_initi
b4a0: 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76  alize() will inv
b4b0: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  oke.** sqlite3_o
b4c0: 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c  s_init().  Simil
b4d0: 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73  arly, ^sqlite3_s
b4e0: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c  hutdown().** wil
b4f0: 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  l invoke sqlite3
b500: 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a  _os_end()..**.**
b510: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
b520: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
b530: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
b540: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
b550: 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f  s..** ^If for so
b560: 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74  me reason, sqlit
b570: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
b580: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69  is unable to ini
b590: 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c  tialize.** the l
b5a0: 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20  ibrary (perhaps 
b5b0: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
b5c0: 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65  allocate a neede
b5d0: 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a  d resource such.
b5e0: 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69  ** as a mutex) i
b5f0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72  t returns an [er
b600: 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20  ror code] other 
b610: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
b620: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
b630: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
b640: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
b650: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
b660: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
b670: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
b680: 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
b690: 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
b6a0: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
b6b0: 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
b6c0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
b6d0: 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
b6e0: 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
b6f0: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
b700: 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
b710: 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
b720: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
b730: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
b740: 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
b750: 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
b760: 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
b770: 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
b780: 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
b790: 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f  ** already.  ^Ho
b7a0: 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65  wever, if SQLite
b7b0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
b7c0: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d  h the [SQLITE_OM
b7d0: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20  IT_AUTOINIT].** 
b7e0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
b7f0: 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75  ion, then the au
b800: 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f  tomatic calls to
b810: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
b820: 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69  ize().** are omi
b830: 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70  tted and the app
b840: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61  lication must ca
b850: 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ll sqlite3_initi
b860: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
b870: 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69  .** prior to usi
b880: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
b890: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
b8a0: 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74  For maximum port
b8b0: 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69  ability,.** it i
b8c0: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
b8d0: 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  at applications 
b8e0: 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71  always invoke sq
b8f0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
b900: 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70  ().** directly p
b910: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
b920: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
b930: 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72  nterface.  Futur
b940: 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66  e releases.** of
b950: 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75   SQLite may requ
b960: 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74  ire this.  In ot
b970: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62  her words, the b
b980: 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65  ehavior exhibite
b990: 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  d.** when SQLite
b9a0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
b9b0: 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  h [SQLITE_OMIT_A
b9c0: 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62  UTOINIT] might b
b9d0: 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66  ecome the.** def
b9e0: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e  ault behavior in
b9f0: 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
ba00: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
ba10: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
ba20: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74  3_os_init() rout
ba30: 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69  ine does operati
ba40: 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
ba50: 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61  ic.** initializa
ba60: 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
ba70: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
ba80: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
ba90: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  ).** routine und
baa0: 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
bab0: 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
bac0: 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61  t().  Typical ta
bad0: 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  sks.** performed
bae0: 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e   by these routin
baf0: 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63  es include alloc
bb00: 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  ation or dealloc
bb10: 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74  ation.** of stat
bb20: 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e  ic resources, in
bb30: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
bb40: 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73  global variables
bb50: 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20  ,.** setting up 
bb60: 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  a default [sqlit
bb70: 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20  e3_vfs] module, 
bb80: 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a  or setting up.**
bb90: 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69   a default confi
bba0: 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b  guration using [
bbb0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
bbc0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  ]..**.** The app
bbd0: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
bbe0: 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74  never invoke eit
bbf0: 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  her sqlite3_os_i
bc00: 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  nit().** or sqli
bc10: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72  te3_os_end() dir
bc20: 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c  ectly.  The appl
bc30: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f  ication should o
bc40: 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  nly invoke.** sq
bc50: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
bc60: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73  () and sqlite3_s
bc70: 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20  hutdown().  The 
bc80: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
bc90: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
bca0: 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74  s called automat
bcb0: 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
bcc0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
bcd0: 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  nd.** sqlite3_os
bce0: 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64  _end() is called
bcf0: 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74   by sqlite3_shut
bd00: 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72  down().  Appropr
bd10: 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  iate.** implemen
bd20: 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69  tations for sqli
bd30: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
bd40: 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
bd50: 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20  ().** are built 
bd60: 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e  into SQLite when
bd70: 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20   it is compiled 
bd80: 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77  for Unix, Window
bd90: 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57  s, or OS/2..** W
bda0: 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c  hen [custom buil
bdb0: 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f  ds | built for o
bdc0: 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a  ther platforms].
bdd0: 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53  ** (using the [S
bde0: 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31  QLITE_OS_OTHER=1
bdf0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
be00: 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70  * option) the ap
be10: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
be20: 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65  upply a suitable
be30: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
be40: 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
be50: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
be60: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20  ite3_os_end().  
be70: 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  An application-s
be80: 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65  upplied.** imple
be90: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
bea0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f  ite3_os_init() o
beb0: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
bec0: 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72  ().** must retur
bed0: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
bee0: 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d   success and som
bef0: 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63  e other [error c
bf00: 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69  ode] upon.** fai
bf10: 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lure..*/.int sql
bf20: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
bf30: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
bf40: 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
bf50: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
bf60: 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e  s_init(void);.in
bf70: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  t sqlite3_os_end
bf80: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
bf90: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
bfa0: 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20  ring The SQLite 
bfb0: 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68  Library.**.** Th
bfc0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
bfd0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
bfe0: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f  used to make glo
bff0: 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  bal configuratio
c000: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
c010: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
c020: 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74  to tune SQLite t
c030: 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
c040: 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61  eeds of.** the a
c050: 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
c060: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
c070: 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d  ration is recomm
c080: 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a  ended for most.*
c090: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * applications a
c0a0: 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69  nd so this routi
c0b0: 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  ne is usually no
c0c0: 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74  t necessary.  It
c0d0: 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20   is.** provided 
c0e0: 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20  to support rare 
c0f0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74  applications wit
c100: 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e  h unusual needs.
c110: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
c120: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
c130: 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72  rface is not thr
c140: 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70  eadsafe.  The ap
c150: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
c160: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t insure that no
c170: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
c180: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
c190: 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
c1a0: 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
c1b0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
c1c0: 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72  is running.  Fur
c1d0: 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65  thermore, sqlite
c1e0: 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61  3_config().** ma
c1f0: 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
c200: 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
c210: 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
c220: 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
c230: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
c240: 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
c250: 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
c260: 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
c270: 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ^If sqlite3_conf
c280: 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ig() is called a
c290: 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e  fter [sqlite3_in
c2a0: 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20  itialize()] and 
c2b0: 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  before.** [sqlit
c2c0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74  e3_shutdown()] t
c2d0: 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75  hen it will retu
c2e0: 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
c2f0: 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76  ..** Note, howev
c300: 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65  er, that ^sqlite
c310: 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62  3_config() can b
c320: 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74  e called as part
c330: 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   of the.** imple
c340: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  mentation of an 
c350: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
c360: 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f  ned [sqlite3_os_
c370: 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  init()]..**.** T
c380: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
c390: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  t to sqlite3_con
c3a0: 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65  fig() is an inte
c3b0: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  ger.** [SQLITE_C
c3c0: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
c3d0: 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  AD | configurati
c3e0: 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
c3f0: 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
c400: 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
c410: 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
c420: 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
c430: 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
c440: 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
c450: 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54  ng on the [SQLIT
c460: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
c470: 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72  HREAD | configur
c480: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
c490: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
c4a0: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
c4b0: 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
c4c0: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
c4d0: 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
c4e0: 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
c4f0: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
c500: 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
c510: 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
c520: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
c530: 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
c540: 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
c550: 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
c560: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
c570: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
c580: 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
c590: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
c5a0: 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
c5b0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
c5c0: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ns.**.** The sql
c5d0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
c5e0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
c5f0: 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
c600: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
c610: 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
c620: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
c630: 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
c640: 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
c650: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
c660: 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
c670: 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
c680: 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
c690: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
c6a0: 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
c6b0: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
c6c0: 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a  gument).  The.**
c6d0: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
c6e0: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ig() interface s
c6f0: 68 6f 75 6c 64 20 6f 6e 6c 79 20 62 65 20 75 73  hould only be us
c700: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61  ed immediately a
c710: 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61  fter.** the data
c720: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
c730: 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  is created using
c740: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
c750: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ],.** [sqlite3_o
c760: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71  pen16()], or [sq
c770: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
c780: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  .  .**.** The se
c790: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
c7a0: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
c7b0: 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
c7c0: 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  the.** configura
c7d0: 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69  tion verb - an i
c7e0: 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
c7f0: 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a   indicates what.
c800: 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  ** aspect of the
c810: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
c820: 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
c830: 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54  configured..** T
c840: 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66  he only choice f
c850: 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20 69 73  or this value is
c860: 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
c870: 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a  G_LOOKASIDE]..**
c880: 20 4e 65 77 20 76 65 72 62 73 20 61 72 65 20 6c   New verbs are l
c890: 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 64 65  ikely to be adde
c8a0: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
c8b0: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
c8c0: 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 61 72  ** Additional ar
c8d0: 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 20 6f  guments depend o
c8e0: 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a  n the verb..**.*
c8f0: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
c900: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
c910: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
c920: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
c930: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
c940: 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
c950: 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sful..*/.int sql
c960: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
c970: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
c980: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
c990: 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
c9a0: 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
c9b0: 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
c9c0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
c9d0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
c9e0: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
c9f0: 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
ca00: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
ca10: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
ca20: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
ca30: 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
ca40: 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
ca50: 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
ca60: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
ca70: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
ca80: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
ca90: 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
caa0: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
cab0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
cac0: 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
cad0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
cae0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
caf0: 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
cb00: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
cb10: 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
cb20: 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
cb30: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
cb40: 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
cb50: 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
cb60: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
cb70: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
cb80: 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
cb90: 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
cba0: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
cbb0: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
cbc0: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
cbd0: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
cbe0: 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
cbf0: 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
cc00: 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
cc10: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
cc20: 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
cc30: 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
cc40: 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
cc50: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
cc60: 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
cc70: 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
cc80: 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
cc90: 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
cca0: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
ccb0: 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
ccc0: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
ccd0: 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
cce0: 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
ccf0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
cd00: 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
cd10: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
cd20: 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
cd30: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
cd40: 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
cd50: 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
cd60: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
cd70: 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
cd80: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
cd90: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
cda0: 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
cdb0: 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
cdc0: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
cdd0: 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
cde0: 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
cdf0: 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
ce00: 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
ce10: 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
ce20: 20 54 68 65 20 78 4d 61 6c 6c 6f 63 20 61 6e 64   The xMalloc and
ce30: 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d   xFree methods m
ce40: 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68  ust work like th
ce50: 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  e.** malloc() an
ce60: 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f  d free() functio
ce70: 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ns from the stan
ce80: 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
ce90: 2a 2a 20 54 68 65 20 78 52 65 61 6c 6c 6f 63 20  ** The xRealloc 
cea0: 6d 65 74 68 6f 64 20 6d 75 73 74 20 77 6f 72 6b  method must work
ceb0: 20 6c 69 6b 65 20 72 65 61 6c 6c 6f 63 28 29 20   like realloc() 
cec0: 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
ced0: 64 20 43 20 6c 69 62 72 61 72 79 0a 2a 2a 20 77  d C library.** w
cee0: 69 74 68 20 74 68 65 20 65 78 63 65 70 74 69 6f  ith the exceptio
cef0: 6e 20 74 68 61 74 20 69 66 20 74 68 65 20 73 65  n that if the se
cf00: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
cf10: 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 7a 65 72   xRealloc is zer
cf20: 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 6d  o,.** xRealloc m
cf30: 75 73 74 20 62 65 20 61 20 6e 6f 2d 6f 70 20 2d  ust be a no-op -
cf40: 20 69 74 20 6d 75 73 74 20 6e 6f 74 20 70 65 72   it must not per
cf50: 66 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f 63 61 74  form any allocat
cf60: 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f  ion or.** deallo
cf70: 63 61 74 69 6f 6e 2e 20 20 5e 53 51 4c 69 74 65  cation.  ^SQLite
cf80: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
cf90: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
cfa0: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
cfb0: 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
cfc0: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
cfd0: 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
cfe0: 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41  o xRoundup..** A
cff0: 6e 64 20 73 6f 20 69 6e 20 63 61 73 65 73 20 77  nd so in cases w
d000: 68 65 72 65 20 78 52 6f 75 6e 64 75 70 20 61 6c  here xRoundup al
d010: 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 70  ways returns a p
d020: 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 2c 0a  ositive number,.
d030: 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 63 61 6e 20  ** xRealloc can 
d040: 70 65 72 66 6f 72 6d 20 65 78 61 63 74 6c 79 20  perform exactly 
d050: 61 73 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  as the standard 
d060: 6c 69 62 72 61 72 79 20 72 65 61 6c 6c 6f 63 28  library realloc(
d070: 29 20 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20 62  ) and.** still b
d080: 65 20 69 6e 20 63 6f 6d 70 6c 69 61 6e 63 65 20  e in compliance 
d090: 77 69 74 68 20 74 68 69 73 20 73 70 65 63 69 66  with this specif
d0a0: 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78  ication..**.** x
d0b0: 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
d0c0: 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
d0d0: 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
d0e0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
d0f0: 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
d100: 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
d110: 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
d120: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
d130: 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
d140: 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
d150: 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
d160: 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
d170: 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
d180: 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
d190: 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
d1a0: 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
d1b0: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
d1c0: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
d1d0: 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
d1e0: 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
d1f0: 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
d200: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
d210: 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
d220: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
d230: 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
d240: 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
d250: 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
d260: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
d270: 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
d280: 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
d290: 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
d2a0: 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
d2b0: 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
d2c0: 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
d2d0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
d2e0: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
d2f0: 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
d300: 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
d310: 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
d320: 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
d330: 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
d340: 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
d350: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
d360: 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
d370: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
d380: 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
d390: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
d3a0: 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (For example,.**
d3b0: 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
d3c0: 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
d3d0: 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
d3e0: 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
d3f0: 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
d400: 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
d410: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
d420: 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
d430: 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
d440: 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
d450: 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
d460: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
d470: 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
d480: 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
d490: 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
d4a0: 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
d4b0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
d4c0: 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
d4d0: 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
d4e0: 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
d4f0: 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
d500: 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
d510: 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
d520: 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
d530: 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
d540: 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
d550: 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
d560: 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
d570: 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
d580: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
d590: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
d5a0: 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
d5b0: 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
d5c0: 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
d5d0: 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
d5e0: 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
d5f0: 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
d600: 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
d610: 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
d620: 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
d630: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
d640: 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
d650: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
d660: 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
d670: 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
d680: 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
d690: 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
d6a0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
d6b0: 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
d6c0: 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
d6d0: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
d6e0: 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
d6f0: 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
d700: 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
d710: 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
d720: 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
d730: 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
d740: 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
d750: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
d760: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
d770: 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
d780: 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
d790: 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
d7a0: 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
d7b0: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
d7c0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
d7d0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
d7e0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
d7f0: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
d800: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
d810: 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
d820: 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
d830: 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
d840: 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
d850: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
d860: 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
d870: 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
d880: 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
d890: 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
d8a0: 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
d8b0: 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
d8c0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
d8d0: 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
d8e0: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
d8f0: 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
d900: 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
d910: 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
d920: 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
d930: 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
d940: 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
d950: 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
d960: 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
d970: 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
d980: 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
d990: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
d9a0: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
d9b0: 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
d9c0: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
d9d0: 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
d9e0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
d9f0: 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
da00: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
da10: 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
da20: 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
da30: 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
da40: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
da50: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
da60: 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
da70: 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
da80: 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
da90: 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
daa0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
dab0: 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
dac0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
dad0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
dae0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
daf0: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
db00: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
db10: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
db20: 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
db30: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
db40: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
db50: 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
db60: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
db70: 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
db80: 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
db90: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
dba0: 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
dbb0: 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
dbc0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  e3_config()] to 
dbd0: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
dbe0: 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
dbf0: 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  d.  The [sqlite3
dc00: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
dc10: 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
dc20: 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
dc30: 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
dc40: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
dc50: 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
dc60: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
dc70: 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
dc80: 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
dc90: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
dca0: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64  _SINGLETHREAD</d
dcb0: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
dcc0: 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
dcd0: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
dce0: 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
dcf0: 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
dd00: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
dd10: 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49  ingle-thread.  I
dd20: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
dd30: 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c  t disables.** al
dd40: 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70  l mutexing and p
dd50: 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20  uts SQLite into 
dd60: 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20  a mode where it 
dd70: 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
dd80: 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20  .** by a single 
dd90: 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51  thread.   ^If SQ
dda0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
ddb0: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
ddc0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
ddd0: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
dde0: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
ddf0: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
de00: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
de10: 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20  sible to change 
de20: 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
de30: 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65  ode] from its de
de40: 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f  fault.** value o
de50: 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  f Single-thread 
de60: 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f  and so [sqlite3_
de70: 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
de80: 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  eturn .** [SQLIT
de90: 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
dea0: 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
deb0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
dec0: 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67  THREAD.** config
ded0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
dee0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
def0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
df00: 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
df10: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
df20: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
df30: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
df40: 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
df50: 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
df60: 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
df70: 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
df80: 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
df90: 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
dfa0: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
dfb0: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
dfc0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
dfd0: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
dfe0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
dff0: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
e000: 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
e010: 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
e020: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
e030: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
e040: 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
e050: 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
e060: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
e070: 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
e080: 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
e090: 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
e0a0: 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
e0b0: 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
e0c0: 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
e0d0: 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
e0e0: 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
e0f0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
e100: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
e110: 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
e120: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
e130: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
e140: 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
e150: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
e160: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
e170: 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
e180: 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
e190: 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
e1a0: 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
e1b0: 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
e1c0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e1d0: 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
e1e0: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
e1f0: 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
e200: 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
e210: 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
e220: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
e230: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
e240: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
e250: 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
e260: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
e270: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
e280: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
e290: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
e2a0: 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
e2b0: 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
e2c0: 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
e2d0: 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
e2e0: 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
e2f0: 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
e300: 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
e310: 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
e320: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
e330: 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
e340: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
e350: 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
e360: 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
e370: 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
e380: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
e390: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
e3a0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
e3b0: 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
e3c0: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
e3d0: 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
e3e0: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
e3f0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e400: 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
e410: 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
e420: 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
e430: 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
e440: 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
e450: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
e460: 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
e470: 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
e480: 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
e490: 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
e4a0: 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
e4b0: 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
e4c0: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
e4d0: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
e4e0: 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
e4f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
e500: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
e510: 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
e520: 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
e530: 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
e540: 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
e550: 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
e560: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
e570: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
e580: 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
e590: 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
e5a0: 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
e5b0: 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
e5c0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
e5d0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
e5e0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
e5f0: 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
e600: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
e610: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
e620: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
e630: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
e640: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
e650: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
e660: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
e670: 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
e680: 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
e690: 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
e6a0: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
e6b0: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
e6c0: 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
e6d0: 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
e6e0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
e6f0: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
e700: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
e710: 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
e720: 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
e730: 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
e740: 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
e750: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
e760: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
e770: 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
e780: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
e790: 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
e7a0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
e7b0: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
e7c0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
e7d0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
e7e0: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
e7f0: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
e800: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
e810: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
e820: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
e830: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
e840: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
e850: 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  em_methods].** s
e860: 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
e870: 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
e880: 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65  ently defined me
e890: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e8a0: 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
e8b0: 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
e8c0: 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
e8d0: 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
e8e0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
e8f0: 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
e900: 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74  h a wrapper that
e910: 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d   simulations mem
e920: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
e930: 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61  ailure or.** tra
e940: 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  cks memory usage
e950: 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c  , for example. <
e960: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
e970: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
e980: 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  STATUS</dt>.** <
e990: 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
e9a0: 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72   takes single ar
e9b0: 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
e9c0: 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20  nt, interpreted 
e9d0: 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e  as a .** boolean
e9e0: 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20  , which enables 
e9f0: 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
ea00: 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65  collection of me
ea10: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
ea20: 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20  .** statistics. 
ea30: 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c  ^(When memory al
ea40: 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
ea50: 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ics are disabled
ea60: 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77  , the .** follow
ea70: 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ing SQLite inter
ea80: 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e  faces become non
ea90: 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
eaa0: 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
eab0: 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
eac0: 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
ead0: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
eae0: 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
eaf0: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
eb00: 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
eb10: 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c  mit64()].**   <l
eb20: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74  i> [sqlite3_stat
eb30: 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e  us()].**   </ul>
eb40: 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c  )^.** ^Memory al
eb50: 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
eb60: 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  ics are enabled 
eb70: 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73  by default unles
eb80: 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  s SQLite is.** c
eb90: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
eba0: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
ebb0: 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69  STATUS]=0 in whi
ebc0: 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a  ch case memory.*
ebd0: 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  * allocation sta
ebe0: 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
ebf0: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
ec00: 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
ec10: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
ec20: 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a  G_SCRATCH</dt>.*
ec30: 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
ec40: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
ec50: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
ec60: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
ec70: 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
ec80: 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20  scratch memory. 
ec90: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
eca0: 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70   arguments:  A p
ecb0: 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65  ointer an 8-byte
ecc0: 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f  .** aligned memo
ecd0: 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77  ry buffer from w
ece0: 68 69 63 68 20 74 68 65 20 73 63 72 61 63 68 20  hich the scrach 
ecf0: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c  allocations will
ed00: 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68   be.** drawn, th
ed10: 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73  e size of each s
ed20: 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
ed30: 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74  n (sz),.** and t
ed40: 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
ed50: 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c  r of scratch all
ed60: 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54  ocations (N).  T
ed70: 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e  he sz.** argumen
ed80: 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74  t must be a mult
ed90: 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54  iple of 16..** T
eda0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
edb0: 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e  t must be a poin
edc0: 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
edd0: 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a   aligned buffer.
ede0: 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  ** of at least s
edf0: 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
ee00: 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
ee10: 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65  will use no more
ee20: 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63   than two scratc
ee30: 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68  h buffers per th
ee40: 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73  read.  So.** N s
ee50: 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20  hould be set to 
ee60: 74 77 69 63 65 20 74 68 65 20 65 78 70 65 63 74  twice the expect
ee70: 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ed maximum numbe
ee80: 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a  r of threads..**
ee90: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65   ^SQLite will ne
eea0: 76 65 72 20 72 65 71 75 69 72 65 20 61 20 73 63  ver require a sc
eeb0: 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61  ratch buffer tha
eec0: 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36  t is more than 6
eed0: 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61  .** times the da
eee0: 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65  tabase page size
eef0: 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65  . ^If SQLite nee
ef00: 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f  ds needs additio
ef10: 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d  nal.** scratch m
ef20: 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61  emory beyond wha
ef30: 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
ef40: 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   this configurat
ef50: 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ion option, then
ef60: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
ef70: 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20  lloc()] will be 
ef80: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
ef90: 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64  he memory needed
efa0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
efb0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
efc0: 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  AGECACHE</dt>.**
efd0: 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
efe0: 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
eff0: 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
f000: 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
f010: 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74  can use for.** t
f020: 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
f030: 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20   cache with the 
f040: 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63  default page cac
f050: 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e  he implemenation
f060: 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
f070: 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64  iguration should
f080: 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20   not be used if 
f090: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
f0a0: 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61  efine page.** ca
f0b0: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
f0c0: 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69  on is loaded usi
f0d0: 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  ng the SQLITE_CO
f0e0: 4e 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74 69  NFIG_PCACHE opti
f0f0: 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  on..** There are
f100: 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
f110: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a   to this option:
f120: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d   A pointer to 8-
f130: 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20  byte aligned.** 
f140: 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65  memory, the size
f150: 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75   of each page bu
f160: 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74  ffer (sz), and t
f170: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
f180: 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73  es (N)..** The s
f190: 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  z argument shoul
f1a0: 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66  d be the size of
f1b0: 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
f1c0: 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61  abase page.** (a
f1d0: 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
f1e0: 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32  tween 512 and 32
f1f0: 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74  768) plus a litt
f200: 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63  le extra for eac
f210: 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
f220: 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61  .  ^The page hea
f230: 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74  der size is 20 t
f240: 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e  o 40 bytes depen
f250: 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68  ding on.** the h
f260: 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65  ost architecture
f270: 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65  .  ^It is harmle
f280: 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74  ss, apart from t
f290: 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79  he wasted memory
f2a0: 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20  ,.** to make sz 
f2b0: 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72  a little too lar
f2c0: 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ge.  The first.*
f2d0: 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
f2e0: 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c  d point to an al
f2f0: 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c  location of at l
f300: 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
f310: 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
f320: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
f330: 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64  he memory provid
f340: 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
f350: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69  argument to sati
f360: 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72  sfy its.** memor
f370: 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20  y needs for the 
f380: 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68  first N pages th
f390: 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61  at it adds to ca
f3a0: 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69  che.  ^If additi
f3b0: 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63  onal.** page cac
f3c0: 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65  he memory is nee
f3d0: 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ded beyond what 
f3e0: 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
f3f0: 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  his option, then
f400: 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20  .** SQLite goes 
f410: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
f420: 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64  oc()] for the ad
f430: 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65  ditional storage
f440: 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70   space..** The p
f450: 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69  ointer in the fi
f460: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
f470: 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20  t.** be aligned 
f480: 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
f490: 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
f4a0: 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
f4b0: 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62  SQLite.** will b
f4c0: 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64  e undefined.</dd
f4d0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
f4e0: 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f  TE_CONFIG_HEAP</
f4f0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
f500: 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
f510: 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
f520: 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
f530: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
f540: 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  * for all of its
f550: 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
f560: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
f570: 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72   beyond those pr
f580: 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79  ovided.** for by
f590: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
f5a0: 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51  SCRATCH] and [SQ
f5b0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
f5c0: 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65  CACHE]..** There
f5d0: 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
f5e0: 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20  ents: An 8-byte 
f5f0: 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20  aligned pointer 
f600: 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a  to the memory,.*
f610: 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
f620: 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d  bytes in the mem
f630: 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20  ory buffer, and 
f640: 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
f650: 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20  cation size..** 
f660: 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f  ^If the first po
f670: 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
f680: 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55  y pointer) is NU
f690: 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  LL, then SQLite 
f6a0: 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73  reverts.** to us
f6b0: 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20  ing its default 
f6c0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
f6d0: 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c   (the system mal
f6e0: 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61  loc() implementa
f6f0: 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e  tion),.** undoin
f700: 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f  g any prior invo
f710: 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54  cation of [SQLIT
f720: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
f730: 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65  .  ^If the.** me
f740: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
f750: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74  not NULL and eit
f760: 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  her [SQLITE_ENAB
f770: 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a  LE_MEMSYS3] or.*
f780: 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
f790: 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65  _MEMSYS5] are de
f7a0: 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20  fined, then the 
f7b0: 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  alternative memo
f7c0: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20  ry.** allocator 
f7d0: 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61  is engaged to ha
f7e0: 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69  ndle all of SQLi
f7f0: 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tes memory alloc
f800: 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20  ation needs..** 
f810: 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  The first pointe
f820: 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
f830: 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61  inter) must be a
f840: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
f850: 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20  yte.** boundary 
f860: 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
f870: 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
f880: 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
f890: 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
f8a0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
f8b0: 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  _MUTEX</dt>.** <
f8c0: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
f8d0: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
f8e0: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
f8f0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
f900: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
f910: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
f920: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
f930: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
f940: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
f950: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
f960: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20  low-level mutex 
f970: 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
f980: 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20  sed in place.** 
f990: 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  the mutex routin
f9a0: 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
f9b0: 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65  Lite.)^  ^SQLite
f9c0: 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
f9d0: 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20   the.** content 
f9e0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
f9f0: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
fa00: 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20  tructure before 
fa10: 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  the call to.** [
fa20: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
fa30: 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53  ] returns. ^If S
fa40: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
fa50: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
fa60: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
fa70: 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
fa80: 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
fa90: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
faa0: 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
fab0: 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
fac0: 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
fad0: 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
fae0: 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
faf0: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
fb00: 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
fb10: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
fb20: 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
fb30: 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
fb40: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
fb50: 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
fb60: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
fb70: 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e  IG_GETMUTEX</dt>
fb80: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
fb90: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
fba0: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
fbb0: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
fbc0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
fbd0: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
fbe0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
fbf0: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
fc00: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
fc10: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
fc20: 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
fc30: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
fc40: 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
fc50: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29  mutex routines.)
fc60: 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
fc70: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
fc80: 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
fc90: 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63  ault mutex alloc
fca0: 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
fcb0: 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
fcc0: 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d   used to track m
fcd0: 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70  utex usage for p
fce0: 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72  erformance.** pr
fcf0: 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69  ofiling or testi
fd00: 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ng, for example.
fd10: 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
fd20: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
fd30: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
fd40: 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
fd50: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
fd60: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
fd70: 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
fd80: 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
fd90: 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
fda0: 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
fdb0: 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
fdc0: 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
fdd0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
fde0: 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
fdf0: 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e  FIG_GETMUTEX con
fe00: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
fe10: 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
fe20: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
fe30: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
fe40: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
fe50: 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
fe60: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
fe70: 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
fe80: 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
fe90: 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c  rmine the defaul
fea0: 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t.** memory allo
feb0: 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c  cation for the l
fec0: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
fed0: 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63  allocator on eac
fee0: 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
fef0: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
ff00: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
ff10: 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
ff20: 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
ff30: 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64   buffer slot and
ff40: 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74   the second is t
ff50: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
ff60: 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20  slots allocated 
ff70: 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
ff80: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20   connection.)^  
ff90: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65  ^(This option se
ffa0: 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66  ts the.** <i>def
ffb0: 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69  ault</i> lookasi
ffc0: 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51  de size. The [SQ
ffd0: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
ffe0: 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62  OKASIDE].** verb
fff0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
10000 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
10010 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
10020 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
10030 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10040 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
10050 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
10060 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
10070 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
10080 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
10090 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
100a0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
100b0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
100c0 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20  ointer to.** an 
100d0 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
100e0 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
100f0 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70    This object sp
10100 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65  ecifies the inte
10110 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75  rface.** to a cu
10120 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20  stom page cache 
10130 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29  implementation.)
10140 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
10150 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
10160 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65  * object and use
10170 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61  s it for page ca
10180 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  che memory alloc
10190 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ations.</dd>.**.
101a0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
101b0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f  NFIG_GETPCACHE</
101c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
101d0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
101e0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
101f0 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
10200 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
10210 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
10220 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20  thods] object.  
10230 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
10240 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
10250 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
10260 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
10270 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
10280 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
10290 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
102a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
102b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
102c0 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOG option takes
102d0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20   two arguments: 
102e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a  a pointer to a.*
102f0 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  * function with 
10300 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65  a call signature
10310 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   of void(*)(void
10320 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
10330 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f  *), .** and a po
10340 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e  inter to void. ^
10350 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
10360 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
10370 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e  ULL, it is.** in
10380 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65  voked by [sqlite
10390 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63  3_log()] to proc
103a0 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67  ess each logging
103b0 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
103c0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  .** function poi
103d0 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68  nter is NULL, th
103e0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  e [sqlite3_log()
103f0 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f  ] interface beco
10400 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20  mes a no-op..** 
10410 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65  ^The void pointe
10420 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65  r that is the se
10430 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
10440 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
10450 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  OG is.** passed 
10460 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
10470 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
10480 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
10490 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
104a0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  .** function whe
104b0 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74  never that funct
104c0 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
104d0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
104e0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
104f0 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
10500 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
10510 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
10520 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70  r to the corresp
10530 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  onding.** [sqlit
10540 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61  e3_log()] call a
10550 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  nd is intended t
10560 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63  o be a [result c
10570 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  ode] or an.** [e
10580 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
10590 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72  ode].  ^The thir
105a0 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  d parameter pass
105b0 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72  ed to the logger
105c0 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61   is.** log messa
105d0 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74  ge after formatt
105e0 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ing via [sqlite3
105f0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a  _snprintf()]..**
10600 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67   The SQLite logg
10610 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73  ing interface is
10620 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20   not reentrant; 
10630 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
10640 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
10650 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
10660 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f  on must not invo
10670 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  ke any SQLite in
10680 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61  terface..** In a
10690 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20   multi-threaded 
106a0 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
106b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
106c0 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
106d0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
106e0 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64  threadsafe. </dd
106f0 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  >.**.** </dl>.*/
10700 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10710 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
10720 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
10730 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10740 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
10750 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
10760 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10770 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
10780 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
10790 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
107a0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
107b0 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
107c0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
107d0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
107e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
107f0 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
10800 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
10810 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
10820 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
10830 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
10840 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
10850 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
10860 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10870 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
10880 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
10890 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
108a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
108b0 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
108c0 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
108d0 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
108e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
108f0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
10900 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
10910 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
10920 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
10930 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
10940 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
10950 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
10960 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
10970 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
10980 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
10990 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
109a0 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
109b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
109c0 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
109d0 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
109e0 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
109f0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
10a00 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
10a10 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
10a20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
10a30 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
10a40 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
10a50 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
10a60 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
10a70 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20  IG_GETPCACHE    
10a80 31 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  15  /* sqlite3_p
10a90 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a  cache_methods* *
10aa0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10ab0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20  _CONFIG_LOG     
10ac0 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e       16  /* xFun
10ad0 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a  c, void* */../*.
10ae0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
10af0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
10b00 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
10b10 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ptions.**.** The
10b20 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
10b30 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
10b40 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
10b50 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
10b60 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
10b70 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
10b80 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
10b90 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
10ba0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
10bb0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
10bc0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10bd0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
10be0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
10bf0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
10c00 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
10c10 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
10c20 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
10c30 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
10c40 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
10c50 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
10c60 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
10c70 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74  3_db_config()] t
10c80 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
10c90 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
10ca0 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69  ked.  ^The [sqli
10cb0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
10cc0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
10cd0 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
10ce0 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
10cf0 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
10d00 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
10d10 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
10d20 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
10d30 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
10d40 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
10d50 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
10d60 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
10d70 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
10d80 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f  es three additio
10d90 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68  nal arguments th
10da0 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
10db0 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20   .** [lookaside 
10dc0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
10dd0 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
10de0 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73  for the [databas
10df0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
10e00 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
10e10 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64  ument (the third
10e20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
10e30 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
10e40 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ()] is a.** poin
10e50 74 65 72 20 74 6f 20 61 6e 20 6d 65 6d 6f 72 79  ter to an memory
10e60 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66   buffer to use f
10e70 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  or lookaside mem
10e80 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ory..** ^The fir
10e90 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65  st argument afte
10ea0 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43  r the SQLITE_DBC
10eb0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
10ec0 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  verb.** may be N
10ed0 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73  ULL in which cas
10ee0 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  e SQLite will al
10ef0 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f  locate the.** lo
10f00 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69  okaside buffer i
10f10 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c  tself using [sql
10f20 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
10f30 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
10f40 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
10f50 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
10f60 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
10f70 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61  t.  ^The third a
10f80 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
10f90 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
10fa0 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  s.  The size of 
10fb0 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68  the buffer in th
10fc0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10fd0 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
10fe0 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61   than.** or equa
10ff0 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74  l to the product
11000 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
11010 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  nd third argumen
11020 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a  ts.  The buffer.
11030 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  ** must be align
11040 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
11050 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74  boundary.  ^If t
11060 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
11070 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f  nt to.** SQLITE_
11080 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
11090 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74  DE is not a mult
110a0 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73  iple of 8, it is
110b0 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72   internally.** r
110c0 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74  ounded down to t
110d0 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20  he next smaller 
110e0 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20  multiple of 8.  
110f0 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  ^(The lookaside 
11100 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67  memory.** config
11110 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61  uration for a da
11120 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11130 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68  n can only be ch
11140 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a  anged when that.
11150 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
11160 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75   not currently u
11170 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  sing lookaside m
11180 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68  emory, or in oth
11190 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e  er words.** when
111a0 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61   the "current va
111b0 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79  lue" returned by
111c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  .** [sqlite3_db_
111d0 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54  status](D,[SQLIT
111e0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
111f0 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f  DE],...) is zero
11200 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
11210 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
11220 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
11230 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68  configuration wh
11240 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  en lookaside.** 
11250 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65  memory is in use
11260 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66   leaves the conf
11270 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e  iguration unchan
11280 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ged and returns 
11290 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
112a0 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
112b0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
112c0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
112d0 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 30  _LOOKASIDE    10
112e0 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  01  /* void* int
112f0 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20   int */.../*.** 
11300 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
11310 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
11320 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
11330 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
11340 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
11350 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75  sult_codes() rou
11360 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
11370 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20  disables the.** 
11380 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
11390 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20   codes] feature 
113a0 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20  of SQLite. ^The 
113b0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a  extended result.
113c0 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73  ** codes are dis
113d0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
113e0 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20   for historical 
113f0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
11400 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
11410 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
11420 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
11430 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
11440 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
11450 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a  Insert Rowid.**.
11460 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69  ** ^Each entry i
11470 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c  n an SQLite tabl
11480 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  e has a unique 6
11490 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
114a0 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
114b0 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
114c0 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72  "rowid"]. ^The r
114d0 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
114e0 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
114f0 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
11500 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
11510 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
11520 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
11530 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
11540 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
11550 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
11560 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66  red columns. ^If
11570 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
11580 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
11590 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
115a0 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
115b0 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
115c0 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
115d0 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
115e0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
115f0 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
11600 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74  wid] of the most
11610 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65   recent.** succe
11620 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
11630 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
11640 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62   from the [datab
11650 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
11660 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
11670 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 6e  argument.  ^If n
11680 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  o successful [IN
11690 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65  SERT]s.** have e
116a0 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20  ver occurred on 
116b0 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f  that database co
116c0 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69  nnection, zero i
116d0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
116e0 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52  * ^(If an [INSER
116f0 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  T] occurs within
11700 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e   a trigger, then
11710 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
11720 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20  the inserted.** 
11730 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20  row is returned 
11740 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
11750 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
11760 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e  rigger is runnin
11770 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74  g..** But once t
11780 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69  he trigger termi
11790 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65  nates, the value
117a0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
117b0 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76  s routine.** rev
117c0 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74  erts to the last
117d0 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20   value inserted 
117e0 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
117f0 65 72 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a  er fired.)^.**.*
11800 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  * ^An [INSERT] t
11810 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
11820 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
11830 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
11840 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
11850 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
11860 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
11870 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
11880 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
11890 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54  e.  ^Thus INSERT
118a0 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
118b0 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
118c0 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
118d0 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
118e0 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
118f0 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
11900 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
11910 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
11920 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
11930 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65  on fails.  ^(Whe
11940 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
11950 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
11960 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
11970 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
11980 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
11990 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
119a0 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
119b0 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
119c0 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
119d0 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
119e0 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
119f0 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
11a00 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
11a10 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
11a20 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
11a30 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a   interface.)^.**
11a40 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
11a50 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f  poses of this ro
11a60 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52  utine, an [INSER
11a70 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  T] is considered
11a80 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73   to.** be succes
11a90 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20  sful even if it 
11aa0 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20  is subsequently 
11ab0 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
11ac0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
11ad0 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74   is accessible t
11ae0 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
11af0 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73   via the.** [las
11b00 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
11b10 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
11b20 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
11b30 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f  ate thread perfo
11b40 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52  rms a new [INSER
11b50 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  T] on the same.*
11b60 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
11b70 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
11b80 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
11b90 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
11ba0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
11bb0 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
11bc0 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
11bd0 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a  nsert [rowid],.*
11be0 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  * then the value
11bf0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
11c00 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
11c10 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
11c20 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
11c30 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
11c40 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
11c50 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
11c60 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
11c70 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  id]..*/.sqlite3_
11c80 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
11c90 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
11ca0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
11cb0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
11cc0 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
11cd0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
11ce0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
11cf0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
11d00 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73  umber of databas
11d10 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65  e rows that were
11d20 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69   changed.** or i
11d30 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
11d40 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
11d50 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
11d60 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  d SQL statement.
11d70 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ** on the [datab
11d80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
11d90 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
11da0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
11db0 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e  ..** ^(Only chan
11dc0 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72  ges that are dir
11dd0 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20  ectly specified 
11de0 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c  by the [INSERT],
11df0 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72   [UPDATE],.** or
11e00 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
11e10 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ent are counted.
11e20 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e    Auxiliary chan
11e30 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a  ges caused by.**
11e40 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f   triggers or [fo
11e50 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
11e60 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  s] are not count
11e70 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a  ed.)^ Use the.**
11e80 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
11e90 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74  changes()] funct
11ea0 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ion to find the 
11eb0 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
11ec0 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75  changes.** inclu
11ed0 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75  ding changes cau
11ee0 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20  sed by triggers 
11ef0 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20  and foreign key 
11f00 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  actions..**.** ^
11f10 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
11f20 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c  w that are simul
11f30 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54  ated by an [INST
11f40 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a  EAD OF trigger].
11f50 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ** are not count
11f60 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74  ed.  Only real t
11f70 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65  able changes are
11f80 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
11f90 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22  ^(A "row change"
11fa0 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20   is a change to 
11fb0 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
11fc0 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a  a single table.*
11fd0 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49  * caused by an I
11fe0 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f  NSERT, DELETE, o
11ff0 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
12000 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a  nt.  Rows that.*
12010 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73  * are changed as
12020 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66   side effects of
12030 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
12040 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
12050 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41  ,.** rollback, A
12060 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
12070 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f   [DROP TABLE], o
12080 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a  r by any other.*
12090 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20  * mechanisms do 
120a0 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72  not count as dir
120b0 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e  ect row changes.
120c0 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67  )^.**.** A "trig
120d0 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20  ger context" is 
120e0 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75  a scope of execu
120f0 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73  tion that begins
12100 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74   and.** ends wit
12110 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20  h the script of 
12120 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  a [CREATE TRIGGE
12130 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a  R | trigger]. .*
12140 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65  * Most SQL state
12150 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61  ments are.** eva
12160 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f  luated outside o
12170 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20  f any trigger.  
12180 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70  This is the "top
12190 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67   level".** trigg
121a0 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20  er context.  If 
121b0 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20  a trigger fires 
121c0 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76  from the top lev
121d0 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69  el, a.** new tri
121e0 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20  gger context is 
121f0 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20  entered for the 
12200 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74  duration of that
12210 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e   one.** trigger.
12220 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72    Subtriggers cr
12230 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73  eate subcontexts
12240 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74   for their durat
12250 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ion..**.** ^Call
12260 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ing [sqlite3_exe
12270 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
12280 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69  _step()] recursi
12290 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  vely does.** not
122a0 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72   create a new tr
122b0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
122c0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
122d0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
122e0 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74  number of direct
122f0 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20   row changes in 
12300 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
12310 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
12320 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  E, or DELETE sta
12330 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
12340 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65  e same.** trigge
12350 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
12360 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c   ^Thus, when cal
12370 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  led from the top
12380 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e   level, this fun
12390 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
123a0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
123b0 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
123c0 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
123d0 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
123e0 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f  ETE.** that also
123f0 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65   occurred at the
12400 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57   top level.  ^(W
12410 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
12420 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20  f a trigger,.** 
12430 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
12440 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20  ges() interface 
12450 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f  can be called to
12460 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
12470 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69   of.** changes i
12480 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
12490 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e  tly completed IN
124a0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
124b0 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65   DELETE.** state
124c0 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
124d0 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65  body of the same
124e0 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77   trigger..** How
124f0 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72  ever, the number
12500 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e   returned does n
12510 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
12520 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  es.** caused by 
12530 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63  subtriggers sinc
12540 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65  e those have the
12550 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29  ir own context.)
12560 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
12570 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
12580 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
12590 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
125a0 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
125b0 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
125c0 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
125d0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
125e0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
125f0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
12600 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
12610 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12620 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
12630 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
12640 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
12650 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
12660 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64  ned.** is unpred
12670 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
12680 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
12690 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
126a0 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
126b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
126c0 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
126d0 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
126e0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
126f0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
12700 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e  mber of row chan
12710 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49  ges caused by [I
12720 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41  NSERT],.** [UPDA
12730 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
12740 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65  statements since
12750 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
12760 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f  onnection] was o
12770 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20  pened..** ^(The 
12780 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62  count returned b
12790 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  y sqlite3_total_
127a0 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64  changes() includ
127b0 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a  es all changes.*
127c0 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41  * from all [CREA
127d0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
127e0 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61  gger] contexts a
127f0 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  nd changes made 
12800 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  by.** [foreign k
12810 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77  ey actions]. How
12820 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75  ever,.** the cou
12830 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
12840 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64  ude changes used
12850 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52   to implement [R
12860 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
12870 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62  nts,.** do rollb
12880 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72  acks or ABORT pr
12890 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52  ocessing, or [DR
128a0 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73  OP TABLE] proces
128b0 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f  sing.  The.** co
128c0 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
128d0 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65  lude rows of vie
128e0 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20  ws that fire an 
128f0 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
12900 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20  ger],.** though 
12910 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f  if the INSTEAD O
12920 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20  F trigger makes 
12930 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f  changes of its o
12940 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65  wn, those change
12950 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65  s .** are counte
12960 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  d.)^.** ^The sql
12970 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
12980 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f  es() function co
12990 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73  unts the changes
129a0 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74   as soon as.** t
129b0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
129c0 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20  t makes them is 
129d0 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20  completed (when 
129e0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
129f0 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65  ndle.** is passe
12a00 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  d to [sqlite3_re
12a10 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
12a20 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e  e3_finalize()]).
12a30 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
12a40 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
12a50 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
12a60 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
12a70 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
12a80 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c  , and the [total
12a90 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  _changes() SQL f
12aa0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
12ab0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
12ac0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
12ad0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
12ae0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12af0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
12b00 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
12b10 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
12b20 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
12b30 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
12b40 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
12b50 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
12b60 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
12b70 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
12b80 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
12b90 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
12ba0 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
12bb0 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e  ng Query.**.** ^
12bc0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
12bd0 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
12be0 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
12bf0 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
12c00 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
12c10 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
12c20 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
12c30 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
12c40 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
12c50 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
12c60 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
12c70 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
12c80 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
12c90 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
12ca0 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
12cb0 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
12cc0 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
12cd0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ly..**.** ^It is
12ce0 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
12cf0 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20  is routine from 
12d00 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65  a thread differe
12d10 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74  nt from the.** t
12d20 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75  hread that is cu
12d30 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20  rrently running 
12d40 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65  the database ope
12d50 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a  ration.  But it.
12d60 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  ** is not safe t
12d70 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
12d80 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61  ine with a [data
12d90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12da0 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73   that.** is clos
12db0 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73  ed or might clos
12dc0 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  e before sqlite3
12dd0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74  _interrupt() ret
12de0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  urns..**.** ^If 
12df0 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  an SQL operation
12e00 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20   is very nearly 
12e10 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20  finished at the 
12e20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c  time when.** sql
12e30 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
12e40 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e   is called, then
12e50 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61   it might not ha
12e60 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74  ve an opportunit
12e70 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72  y.** to be inter
12e80 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74  rupted and might
12e90 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d   continue to com
12ea0 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  pletion..**.** ^
12eb0 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
12ec0 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
12ed0 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
12ee0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
12ef0 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  PT]..** ^If the 
12f00 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20  interrupted SQL 
12f10 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20  operation is an 
12f20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
12f30 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
12f40 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65  t is inside an e
12f50 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
12f60 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e  ion, then the en
12f70 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  tire transaction
12f80 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c  .** will be roll
12f90 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
12fa0 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cally..**.** ^Th
12fb0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
12fc0 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69  upt(D) call is i
12fd0 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61  n effect until a
12fe0 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  ll currently run
12ff0 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
13000 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62  ements on [datab
13010 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
13020 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e  D complete.  ^An
13030 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d  y new SQL statem
13040 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
13050 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
13060 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
13070 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20  rupt() call and 
13080 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72  before the .** r
13090 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
130a0 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  s reaches zero a
130b0 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  re interrupted a
130c0 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65  s if they had be
130d0 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72  en.** running pr
130e0 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ior to the sqlit
130f0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
13100 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73  all.  ^New SQL s
13110 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
13120 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
13130 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20  ter the running 
13140 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20  statement count 
13150 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
13160 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64  .** not effected
13170 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
13180 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20  interrupt()..** 
13190 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ^A call to sqlit
131a0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
131b0 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e  that occurs when
131c0 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75   there are no ru
131d0 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
131e0 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d  tements is a no-
131f0 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66  op and has no ef
13200 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74  fect on SQL stat
13210 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
13220 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
13230 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
13240 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65  errupt() call re
13250 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  turns..**.** If 
13260 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
13270 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77  nection closes w
13280 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e  hile [sqlite3_in
13290 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73  terrupt()].** is
132a0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61   running then ba
132b0 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69  d things will li
132c0 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a  kely happen..*/.
132d0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
132e0 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
132f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
13300 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
13310 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
13320 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
13330 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
13340 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
13350 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
13360 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
13370 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
13380 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
13390 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
133a0 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
133b0 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
133c0 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
133d0 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
133e0 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
133f0 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
13400 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
13410 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  ng.  ^These rout
13420 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66  ines return 1 if
13430 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
13440 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
13450 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
13460 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41  L statement.  ^A
13470 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
13480 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
13490 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
134a0 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
134b0 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
134c0 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20  not a prefix of 
134d0 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  a.** well-formed
134e0 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
134f0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d  statement.  ^Sem
13500 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
13510 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
13520 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
13530 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
13540 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
13550 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
13560 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
13570 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
13580 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
13590 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
135a0 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
135b0 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
135c0 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
135d0 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
135e0 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63  tor.  ^Whitespac
135f0 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  e.** and comment
13600 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68  s that follow th
13610 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f  e final semicolo
13620 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a  n are ignored..*
13630 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
13640 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66  ines return 0 if
13650 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
13660 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  s incomplete.  ^
13670 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
13680 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
13690 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
136a0 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
136b0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
136c0 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
136d0 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
136e0 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
136f0 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
13700 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
13710 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
13720 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73   ^(If SQLite has
13730 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61   not been initia
13740 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  lized using [sql
13750 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
13760 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20  )] prior .** to 
13770 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  invoking sqlite3
13780 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68  _complete16() th
13790 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  en sqlite3_initi
137a0 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
137b0 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ed.** automatica
137c0 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63  lly by sqlite3_c
137d0 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66  omplete16().  If
137e0 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61   that initializa
137f0 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74  tion fails,.** t
13800 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
13810 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
13820 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77  3_complete16() w
13830 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a  ill be non-zero.
13840 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
13850 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
13860 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73  the input SQL is
13870 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a   complete.)^.**.
13880 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
13890 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
138a0 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
138b0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
138c0 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
138d0 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
138e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
138f0 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
13900 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
13910 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
13920 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
13930 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e  yte order..*/.in
13940 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
13950 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
13960 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ql);.int sqlite3
13970 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
13980 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
13990 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
139a0 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
139b0 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
139c0 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a  ITE_BUSY Errors.
139d0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
139e0 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
139f0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ack function tha
13a00 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
13a10 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61  ed whenever.** a
13a20 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
13a30 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61  e to open a data
13a40 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20  base table that 
13a50 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
13a60 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
13a70 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   locked..**.** ^
13a80 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
13a90 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
13aa0 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
13ab0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
13ac0 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73  R_BLOCKED].** is
13ad0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
13ae0 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
13af0 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
13b00 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
13b10 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
13b20 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
13b30 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
13b40 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
13b50 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
13b60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
13b70 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
13b80 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
13b90 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
13ba0 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
13bb0 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
13bc0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
13bd0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
13be0 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
13bf0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
13c00 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
13c10 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
13c20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
13c30 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
13c40 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
13c50 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f   been invoked fo
13c60 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65  r this locking e
13c70 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
13c80 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
13c90 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
13ca0 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
13cb0 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
13cc0 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
13cd0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
13ce0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
13cf0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
13d00 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
13d10 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  d..** ^If the ca
13d20 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
13d30 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
13d40 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
13d50 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
13d60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
13d70 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
13d80 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
13d90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
13da0 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
13db0 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
13dc0 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
13dd0 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
13de0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
13df0 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
13e00 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65  n. ^If SQLite de
13e10 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
13e20 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
13e30 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
13e40 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
13e50 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
13e60 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
13e70 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
13e80 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
13e90 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e  OERR_BLOCKED] in
13ea0 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
13eb0 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  g the busy handl
13ec0 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
13ed0 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
13ee0 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
13ef0 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
13f00 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
13f10 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
13f20 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
13f30 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
13f40 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
13f50 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
13f60 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
13f70 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
13f80 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
13f90 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
13fa0 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
13fb0 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
13fc0 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
13fd0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
13fe0 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
13ff0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
14000 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
14010 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
14020 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
14030 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
14040 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
14050 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
14060 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
14070 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
14080 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
14090 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
140a0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
140b0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
140c0 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
140d0 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
140e0 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
140f0 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
14100 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
14110 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
14120 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
14130 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
14140 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
14150 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
14160 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
14170 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53  ^The [SQLITE_BUS
14180 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76  Y] error is conv
14190 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45  erted to [SQLITE
141a0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
141b0 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
141c0 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  s in the middle 
141d0 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73  of a large trans
141e0 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c  action where all
141f0 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20   the.** changes 
14200 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74  will not fit int
14210 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20  o the in-memory 
14220 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77  cache.  SQLite w
14230 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68  ill.** already h
14240 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c  old a RESERVED l
14250 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ock on the datab
14260 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74  ase file, but it
14270 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f   needs.** to pro
14280 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74  mote this lock t
14290 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74  o EXCLUSIVE so t
142a0 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c  hat it can spill
142b0 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20   cache.** pages 
142c0 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
142d0 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68  e file without h
142e0 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e  arm to concurren
142f0 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e  t.** readers.  ^
14300 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  If it is unable 
14310 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c  to promote the l
14320 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e  ock, then the in
14330 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65  -memory.** cache
14340 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e   will be left in
14350 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74   an inconsistent
14360 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68   state and so th
14370 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
14380 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d  is promoted from
14390 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20   the relatively 
143a0 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42  benign [SQLITE_B
143b0 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d  USY] to.** the m
143c0 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49  ore severe [SQLI
143d0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
143e0 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20  ].  ^This error 
143f0 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a  code promotion.*
14400 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f  * forces an auto
14410 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f  matic rollback o
14420 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20  f the changes.  
14430 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72  See the.** <a hr
14440 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b  ef="/cvstrac/wik
14450 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f  i?p=CorruptionFo
14460 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
14470 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e  ">.** Corruption
14480 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
14490 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65  or</a> wiki page
144a0 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f   for a discussio
144b0 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73  n of why.** this
144c0 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a   is important..*
144d0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
144e0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
144f0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
14500 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
14510 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
14520 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
14530 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
14540 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
14550 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
14560 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
14570 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
14580 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
14590 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69  timeout()].** wi
145a0 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
145b0 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61  lear the busy ha
145c0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
145d0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
145e0 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
145f0 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
14600 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
14610 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14620 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
14630 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
14640 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
14650 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
14660 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
14670 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
14680 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
14690 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
146a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
146b0 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
146c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
146d0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
146e0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69  sy handler..*/.i
146f0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
14700 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
14710 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  , int(*)(void*,i
14720 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  nt), void*);../*
14730 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
14740 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
14750 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
14760 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
14770 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
14780 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
14790 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
147a0 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
147b0 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
147c0 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
147d0 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61  locked.  ^The ha
147e0 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
147f0 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
14800 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
14810 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
14820 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
14830 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
14840 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20  ted.  ^After at 
14850 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
14860 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
14870 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64  ing,.** the hand
14880 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
14890 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69  ich causes [sqli
148a0 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
148b0 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
148c0 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
148d0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
148e0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
148f0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
14900 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
14910 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
14920 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
14930 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
14940 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
14950 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
14960 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
14970 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20  y handler for a 
14980 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
14990 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
149a0 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65  on] any any give
149b0 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e  n moment.  If an
149c0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
149d0 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65  er.** was define
149e0 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  d  (using [sqlit
149f0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
14a00 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
14a10 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
14a20 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
14a30 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
14a40 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69   cleared.)^.*/.i
14a50 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
14a60 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
14a70 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
14a80 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
14a90 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
14aa0 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
14ab0 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ries.**.** This 
14ac0 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65  is a legacy inte
14ad0 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72  rface that is pr
14ae0 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b  eserved for back
14af0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
14b00 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74  ity..** Use of t
14b10 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
14b20 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64   not recommended
14b30 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69  ..**.** Definiti
14b40 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20  on: A <b>result 
14b50 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d  table</b> is mem
14b60 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75  ory data structu
14b70 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68  re created by th
14b80 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  e.** [sqlite3_ge
14b90 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72  t_table()] inter
14ba0 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20  face.  A result 
14bb0 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68  table records th
14bc0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75  e.** complete qu
14bd0 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  ery results from
14be0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65   one or more que
14bf0 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ries..**.** The 
14c00 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c  table conceptual
14c10 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20  ly has a number 
14c20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75  of rows and colu
14c30 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65  mns.  But.** the
14c40 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e  se numbers are n
14c50 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72  ot part of the r
14c60 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65  esult table itse
14c70 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75  lf.  These.** nu
14c80 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e  mbers are obtain
14c90 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20  ed separately.  
14ca0 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d  Let N be the num
14cb0 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61  ber of rows.** a
14cc0 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62  nd M be the numb
14cd0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  er of columns..*
14ce0 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
14cf0 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20  ble is an array 
14d00 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  of pointers to z
14d10 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
14d20 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  TF-8 strings..**
14d30 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29   There are (N+1)
14d40 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74  *M elements in t
14d50 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66  he array.  The f
14d60 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20  irst M pointers 
14d70 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f  point.** to zero
14d80 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
14d90 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69  ngs that  contai
14da0 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  n the names of t
14db0 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54  he columns..** T
14dc0 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74  he remaining ent
14dd0 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74  ries all point t
14de0 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e  o query results.
14df0 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65    NULL values re
14e00 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20  sult.** in NULL 
14e10 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f  pointers.  All o
14e20 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20  ther values are 
14e30 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a  in their UTF-8 z
14e40 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
14e50 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65  * string represe
14e60 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72  ntation as retur
14e70 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
14e80 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
14e90 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
14ea0 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69  able might consi
14eb0 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  st of one or mor
14ec0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
14ed0 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e  ions..** It is n
14ee0 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20  ot safe to pass 
14ef0 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64  a result table d
14f00 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69  irectly to [sqli
14f10 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20  te3_free()]..** 
14f20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73  A result table s
14f30 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63  hould be dealloc
14f40 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
14f50 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
14f60 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e  ]..**.** ^(As an
14f70 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
14f80 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
14f90 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
14fa0 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
14fb0 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
14fc0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14fd0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
14fe0 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
14ff0 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
15000 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
15010 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
15020 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
15030 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
15040 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
15050 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
15060 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
15070 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
15080 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
15090 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
150a0 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
150b0 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
150c0 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
150d0 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
150e0 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
150f0 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
15100 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
15110 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
15120 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
15130 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
15140 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
15150 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
15160 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
15170 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
15180 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
15190 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
151a0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
151b0 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
151c0 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
151d0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
151e0 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
151f0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
15200 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
15210 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
15220 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
15230 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
15240 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
15250 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
15260 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
15270 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
15280 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
15290 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
152a0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
152b0 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
152c0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
152d0 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
152e0 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
152f0 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
15300 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
15310 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
15320 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
15330 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  nd returns a res
15340 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
15350 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
15360 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
15370 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
15380 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  ter the applicat
15390 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
153a0 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74   with the result
153b0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65   from sqlite3_ge
153c0 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74  t_table(),.** it
153d0 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72   must pass the r
153e0 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
153f0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
15400 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
15410 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
15420 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
15430 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
15440 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
15450 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
15460 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
15470 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
15480 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
15490 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
154a0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
154b0 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
154c0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
154d0 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
154e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
154f0 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
15500 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
15510 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
15520 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
15530 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
15540 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
15550 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
15560 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
15570 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
15580 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
15590 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
155a0 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
155b0 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
155c0 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
155d0 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
155e0 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
155f0 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
15600 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
15610 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
15620 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
15630 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
15640 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
15650 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
15660 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
15670 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
15680 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
15690 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
156a0 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
156b0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
156c0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
156d0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
156e0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e  errmsg()]..*/.in
156f0 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
15700 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ble(.  sqlite3 *
15710 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
15720 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
15730 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
15740 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53   *zSql,     /* S
15750 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
15760 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a  ed */.  char ***
15770 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a  pazResult,    /*
15780 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   Results of the 
15790 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a  query */.  int *
157a0 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20  pnRow,          
157b0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
157c0 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
157d0 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
157e0 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20  *pnColumn,      
157f0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
15800 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72  esult columns wr
15810 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
15820 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20  char **pzErrmsg 
15830 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
15840 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
15850 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  */.);.void sqlit
15860 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
15870 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
15880 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
15890 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
158a0 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
158b0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
158c0 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
158d0 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  -alikes of the "
158e0 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
158f0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
15900 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
15910 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
15920 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
15930 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
15940 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
15950 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
15960 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
15970 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
15980 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
15990 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
159a0 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
159b0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
159c0 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
159d0 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
159e0 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
159f0 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20  free()].  ^Both 
15a00 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
15a10 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
15a20 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
15a30 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
15a40 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
15a50 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
15a60 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
15a70 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
15a80 2a 2a 20 5e 28 49 6e 20 73 71 6c 69 74 65 33 5f  ** ^(In sqlite3_
15a90 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
15aa0 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
15ab0 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
15ac0 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
15ad0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
15ae0 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
15af0 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
15b00 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
15b10 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
15b20 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
15b30 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
15b40 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
15b50 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
15b60 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
15b70 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
15b80 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
15b90 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
15ba0 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20  intf().)^  This 
15bb0 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
15bc0 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
15bd0 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
15be0 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
15bf0 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
15c00 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
15c10 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ^(Note also that
15c20 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
15c30 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
15c40 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
15c50 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
15c60 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
15c70 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
15c80 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
15c90 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29  nto the buffer.)
15ca0 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ^  We admit that
15cb0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
15cc0 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
15cd0 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
15ce0 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
15cf0 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
15d00 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
15d10 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
15d20 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
15d30 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
15d40 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
15d50 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
15d60 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20  .**.** ^As long 
15d70 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
15d80 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
15d90 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
15da0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
15db0 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
15dc0 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
15dd0 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
15de0 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ted.  ^The first
15df0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
15e00 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
15e10 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
15e20 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
15e30 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
15e40 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
15e50 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
15e60 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
15e70 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
15e80 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
15e90 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
15ea0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
15eb0 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72  e3_vsnprintf() r
15ec0 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61  outine is a vara
15ed0 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73  rgs version of s
15ee0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
15ef0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )..**.** These r
15f00 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
15f10 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
15f20 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
15f30 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
15f40 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
15f50 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
15f60 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
15f70 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
15f80 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
15f90 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
15fa0 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
15fb0 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
15fc0 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e  e "%q", "%Q", an
15fd0 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a  d "%z" options..
15fe0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f  **.** ^(The %q o
15ff0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
16000 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73   %s in that it s
16010 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c  ubstitutes a nul
16020 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
16030 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20  string from the 
16040 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20  argument list.  
16050 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62  But %q also doub
16060 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63  les every '\'' c
16070 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20  haracter..** %q 
16080 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20  is designed for 
16090 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72  use inside a str
160a0 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20  ing literal.)^  
160b0 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68  By doubling each
160c0 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74   '\''.** charact
160d0 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68  er it escapes th
160e0 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64  at character and
160f0 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65   allows it to be
16100 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a   inserted into.*
16110 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a  * the string..**
16120 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
16130 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69   assume the stri
16140 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78  ng variable zTex
16150 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20  t contains text 
16160 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
16170 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
16180 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54  re>.**  char *zT
16190 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61  ext = "It's a ha
161a0 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f  ppy day!";.** </
161b0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
161c0 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20  >.**.** One can 
161d0 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e  use this text in
161e0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
161f0 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
16200 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
16210 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
16220 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
16230 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
16240 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
16250 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b  ('%q')", zText);
16260 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
16270 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
16280 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
16290 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
162a0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
162b0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  ote>.**.** Becau
162c0 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74  se the %q format
162d0 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c   string is used,
162e0 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63   the '\'' charac
162f0 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20  ter in zText.** 
16300 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74  is escaped and t
16310 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64  he SQL generated
16320 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
16330 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
16340 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
16350 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
16360 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68  ALUES('It''s a h
16370 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c  appy day!').** <
16380 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
16390 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e>.**.** This is
163a0 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77   correct.  Had w
163b0 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61  e used %s instea
163c0 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e  d of %q, the gen
163d0 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f  erated SQL.** wo
163e0 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20  uld have looked 
163f0 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
16400 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
16410 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
16420 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
16430 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64  ('It's a happy d
16440 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ay!');.** </pre>
16450 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
16460 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20  .** This second 
16470 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51  example is an SQ
16480 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20  L syntax error. 
16490 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75   As a general ru
164a0 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a  le you should.**
164b0 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69   always use %q i
164c0 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65  nstead of %s whe
164d0 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74  n inserting text
164e0 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c   into a string l
164f0 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  iteral..**.** ^(
16500 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f  The %Q option wo
16510 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65  rks like %q exce
16520 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20  pt it also adds 
16530 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72  single quotes ar
16540 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73  ound.** the outs
16550 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c  ide of the total
16560 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69   string.  Additi
16570 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70  onally, if the p
16580 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a  arameter in the.
16590 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  ** argument list
165a0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
165b0 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74  er, %Q substitut
165c0 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c  es the text "NUL
165d0 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73  L" (without.** s
165e0 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e  ingle quotes).)^
165f0 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
16600 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
16610 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
16620 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
16630 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
16640 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
16650 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
16660 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
16670 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
16680 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
16690 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
166a0 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
166b0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
166c0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
166d0 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
166e0 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
166f0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
16700 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
16710 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
16720 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
16730 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
16740 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  nter..**.** ^(Th
16750 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
16760 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  g option works l
16770 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74  ike "%s" but wit
16780 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f  h the.** additio
16790 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65  n that after the
167a0 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e   string has been
167b0 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64   read and copied
167c0 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73   into.** the res
167d0 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ult, [sqlite3_fr
167e0 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ee()] is called 
167f0 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  on the input str
16800 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a  ing.)^.*/.char *
16810 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
16820 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29  const char*,...)
16830 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
16840 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  vmprintf(const c
16850 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
16860 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e  char *sqlite3_sn
16870 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
16880 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e  ,const char*, ..
16890 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
168a0 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  3_vsnprintf(int,
168b0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
168c0 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a  *, va_list);../*
168d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
168e0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
168f0 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20  Subsystem.**.** 
16900 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
16910 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65  uses these three
16920 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c   routines for al
16930 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20  l of its own.** 
16940 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20  internal memory 
16950 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
16960 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20  . "Core" in the 
16970 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
16980 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e  e.** does not in
16990 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d  clude operating-
169a0 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20  system specific 
169b0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
169c0 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64  on.  The.** Wind
169d0 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74  ows VFS uses nat
169e0 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  ive malloc() and
169f0 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65   free() for some
16a00 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
16a10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
16a20 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  malloc() routine
16a30 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
16a40 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a  er to a block.**
16a50 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65   of memory at le
16a60 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c  ast N bytes in l
16a70 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69  ength, where N i
16a80 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  s the parameter.
16a90 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
16aa0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
16ab0 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
16ac0 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
16ad0 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
16ae0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
16af0 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61  r.  ^If the para
16b00 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71  meter N to.** sq
16b10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
16b20 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69  s zero or negati
16b30 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ve then sqlite3_
16b40 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  malloc() returns
16b50 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
16b60 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
16b70 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
16b80 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
16b90 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
16ba0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
16bb0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
16bc0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
16bd0 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
16be0 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
16bf0 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
16c00 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
16c10 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
16c20 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
16c30 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
16c40 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
16c50 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
16c60 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
16c70 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
16c80 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
16c90 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
16ca0 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
16cb0 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
16cc0 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
16cd0 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
16ce0 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
16cf0 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
16d00 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
16d10 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
16d20 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
16d30 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
16d40 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
16d50 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
16d60 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
16d70 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
16d80 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
16d90 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
16da0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
16db0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
16dc0 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
16dd0 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
16de0 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
16df0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
16e00 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
16e10 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65  3_realloc() inte
16e20 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
16e30 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
16e40 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
16e50 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c  ation to be at l
16e60 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68  east N bytes, wh
16e70 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
16e80 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16e90 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c  .  The memory al
16ea0 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72  location to be r
16eb0 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69  esized is the fi
16ec0 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
16ed0 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72  .)^ ^ If the fir
16ee0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
16ef0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
16f00 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  ).** is a NULL p
16f10 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20  ointer then its 
16f20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e  behavior is iden
16f30 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67  tical to calling
16f40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
16f50 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73  oc(N) where N is
16f60 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
16f70 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
16f80 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e  _realloc()..** ^
16f90 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  If the second pa
16fa0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
16fb0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20  e3_realloc() is 
16fc0 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
16fd0 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
16fe0 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
16ff0 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
17000 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
17010 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20  free(P) where P 
17020 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
17030 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
17040 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
17050 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  ^sqlite3_realloc
17060 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
17070 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
17080 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
17090 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
170a0 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
170b0 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74  LL if sufficient
170c0 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61   memory is unava
170d0 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d  ilable..** ^If M
170e0 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
170f0 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
17100 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
17110 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
17120 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
17130 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
17140 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
17150 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
17160 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
17170 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e  te3_realloc() an
17180 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  d the prior allo
17190 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e  cation is freed.
171a0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
171b0 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
171c0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  s NULL, then the
171d0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
171e0 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65  n.** is not free
171f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  d..**.** ^The me
17200 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
17210 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
17220 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
17230 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c  alloc().** is al
17240 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
17250 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
17260 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20  te boundary, or 
17270 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62  to a.** 4 byte b
17280 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b  oundary if the [
17290 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c  SQLITE_4_BYTE_AL
172a0 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f  IGNED_MALLOC] co
172b0 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
172c0 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a  tion is used..**
172d0 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65  .** In SQLite ve
172e0 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20  rsion 3.5.0 and 
172f0 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f  3.5.1, it was po
17300 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65  ssible to define
17310 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  .** the SQLITE_O
17320 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
17330 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c  ATION which woul
17340 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  d cause the buil
17350 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  t-in.** implemen
17360 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20  tation of these 
17370 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f  routines to be o
17380 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61  mitted.  That ca
17390 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e  pability.** is n
173a0 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65  o longer provide
173b0 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69  d.  Only built-i
173c0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
173d0 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e  ors can be used.
173e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f  .**.** The Windo
173f0 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  ws OS interface 
17400 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74  layer calls.** t
17410 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
17420 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69  () and free() di
17430 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76  rectly when conv
17440 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61  erting.** filena
17450 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20  mes between the 
17460 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75  UTF-8 encoding u
17470 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  sed by SQLite.**
17480 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69   and whatever fi
17490 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20  lename encoding 
174a0 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70  is used by the p
174b0 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77  articular Window
174c0 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f  s.** installatio
174d0 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  n.  Memory alloc
174e0 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65  ation errors are
174f0 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
17500 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f 72  * they are repor
17510 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c  ted back as [SQL
17520 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72  ITE_CANTOPEN] or
17530 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
17540 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b  R] rather than [
17550 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
17560 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
17570 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73   arguments to [s
17580 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61  qlite3_free()] a
17590 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
175a0 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  loc()].** must b
175b0 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
175c0 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f   else pointers o
175d0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
175e0 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  rior.** invocati
175f0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
17600 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
17610 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
17620 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74  that have.** not
17630 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
17640 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  ed..**.** The ap
17650 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
17660 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
17670 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
17680 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
17690 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
176a0 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
176b0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
176c0 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
176d0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
176e0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
176f0 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  malloc(int);.voi
17700 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
17710 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
17720 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
17730 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
17740 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
17750 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
17760 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  istics.**.** SQL
17770 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
17780 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
17790 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
177a0 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
177b0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
177c0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
177d0 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
177e0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
177f0 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
17800 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
17810 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
17820 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
17830 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  system..**.** ^T
17840 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
17850 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
17860 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
17870 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
17880 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  * of memory curr
17890 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
178a0 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
178b0 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e  not freed)..** ^
178c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
178d0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
178e0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
178f0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
17900 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
17910 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
17920 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
17930 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61  water mark.** wa
17940 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e  s last reset.  ^
17950 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
17960 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
17970 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
17980 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
17990 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
179a0 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
179b0 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64  verhead.** added
179c0 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
179d0 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
179e0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
179f0 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e  loc()],.** but n
17a00 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
17a10 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
17a20 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
17a30 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e  ibrary.** routin
17a40 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
17a50 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
17a60 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
17a70 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
17a80 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
17a90 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
17aa0 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  alue of.** [sqli
17ab0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
17ac0 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
17ad0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
17ae0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  to.** [sqlite3_m
17af0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
17b00 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68  )] is true.  ^Th
17b10 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
17b20 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
17b30 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
17b40 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
17b50 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70  -water mark.** p
17b60 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
17b70 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  t..*/.sqlite3_in
17b80 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
17b90 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73  ry_used(void);.s
17ba0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
17bb0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
17bc0 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
17bd0 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
17be0 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
17bf0 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
17c00 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rator.**.** SQLi
17c10 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
17c20 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
17c30 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
17c40 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
17c50 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
17c60 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
17c70 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
17c80 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
17c90 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
17ca0 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
17cb0 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
17cc0 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
17cd0 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
17ce0 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
17cf0 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
17d00 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
17d10 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
17d20 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
17d30 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
17d40 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
17d50 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
17d60 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
17d70 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
17d80 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68  ** ^A call to th
17d90 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
17da0 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e  s N bytes of ran
17db0 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
17dc0 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fer P..**.** ^Th
17dd0 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69  e first time thi
17de0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76  s routine is inv
17df0 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74  oked (either int
17e00 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a  ernally or by.**
17e10 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
17e20 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65  ) the PRNG is se
17e30 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f  eded using rando
17e40 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mness obtained.*
17e50 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  * from the xRand
17e60 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
17e70 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
17e80 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
17e90 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75  t..** ^On all su
17ea0 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
17eb0 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f  ions, the pseudo
17ec0 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
17ed0 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
17ee0 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
17ef0 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
17f00 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
17f10 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
17f20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20  method..*/.void 
17f30 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
17f40 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a  ss(int N, void *
17f50 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  P);../*.** CAPI3
17f60 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
17f70 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
17f80 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
17f90 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
17fa0 67 69 73 74 65 72 73 20 61 20 61 75 74 68 6f 72  gisters a author
17fb0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
17fc0 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
17fd0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
17fe0 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
17ff0 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
18000 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
18010 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
18020 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
18030 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
18040 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
18050 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
18060 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
18070 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
18080 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
18090 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
180a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
180b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
180c0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
180d0 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70  ^At various.** p
180e0 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
180f0 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
18100 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
18110 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
18120 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
18130 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
18140 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
18150 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
18160 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
18170 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
18180 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20   allowed.  ^The 
18190 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
181a0 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
181b0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
181c0 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
181d0 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
181e0 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
181f0 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
18200 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
18210 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
18220 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
18230 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
18240 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
18250 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
18260 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
18270 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
18280 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
18290 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65   error.  ^If the
182a0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
182b0 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
182c0 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
182d0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e  than [SQLITE_IGN
182e0 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
182f0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
18300 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  NY].** then the 
18310 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
18320 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
18330 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
18340 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20  riggered.** the 
18350 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
18360 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
18370 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
18380 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
18390 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
183a0 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65  ITE_OK], that me
183b0 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ans the operatio
183c0 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69  n.** requested i
183d0 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65  s ok.  ^When the
183e0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
183f0 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
18400 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
18410 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
18420 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
18430 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
18440 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
18450 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
18460 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
18470 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
18480 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
18490 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e  denied. .**.** ^
184a0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
184b0 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
184c0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
184d0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
184e0 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
184f0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
18500 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
18510 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54  () interface. ^T
18520 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
18530 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
18540 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
18550 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50  eger [SQLITE_COP
18560 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
18570 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
18580 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  ** the particula
18590 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  r action to be a
185a0 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20  uthorized. ^The 
185b0 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
185c0 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  xth parameters.*
185d0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
185e0 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  k are zero-termi
185f0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
18600 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
18610 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73  ional.** details
18620 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
18630 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
18640 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
18650 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
18660 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
18670 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
18680 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
18690 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
186a0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
186b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
186c0 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
186d0 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
186e0 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
186f0 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
18700 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
18710 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
18720 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
18730 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
18740 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
18750 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
18760 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
18770 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
18780 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
18790 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
187a0 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
187b0 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
187c0 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
187d0 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
187e0 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68  E_DELETE] and th
187f0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
18800 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47  ns.** [SQLITE_IG
18810 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b  NORE] then the [
18820 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f  DELETE] operatio
18830 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74  n proceeds but t
18840 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20  he.** [truncate 
18850 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73  optimization] is
18860 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c   disabled and al
18870 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  l rows are delet
18880 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e  ed individually.
18890 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
188a0 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
188b0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
188c0 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a  re | preparing].
188d0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
188e0 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
188f0 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  ted source, to e
18900 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
18910 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
18920 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
18930 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20  ccess data they 
18940 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
18950 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
18960 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74  they do not.** t
18970 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61  ry to execute ma
18980 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
18990 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
189a0 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
189b0 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
189c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
189d0 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
189e0 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
189f0 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
18a00 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
18a10 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
18a20 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
18a30 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
18a40 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
18a50 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
18a60 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
18a70 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
18a80 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
18a90 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
18aa0 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
18ab0 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
18ac0 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
18ad0 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
18ae0 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
18af0 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
18b00 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
18b10 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
18b20 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
18b30 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
18b40 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
18b50 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
18b60 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
18b70 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
18b80 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
18b90 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
18ba0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
18bb0 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
18bc0 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
18bd0 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
18be0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
18bf0 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
18c00 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
18c10 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
18c20 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20  .**.** ^(Only a 
18c30 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
18c40 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
18c50 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
18c60 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
18c70 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
18c80 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
18c90 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
18ca0 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
18cb0 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20  revious call.)^ 
18cc0 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75   ^Disable the au
18cd0 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
18ce0 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
18cf0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
18d00 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
18d10 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
18d20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  ..**.** The auth
18d30 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
18d40 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
18d50 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
18d60 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
18d70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18d80 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
18d90 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
18da0 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74  lback..** Note t
18db0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
18dc0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
18dd0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
18de0 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
18df0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
18e00 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
18e10 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
18e20 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
18e30 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
18e40 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  When [sqlite3_pr
18e50 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75  epare_v2()] is u
18e60 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61  sed to prepare a
18e70 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a   statement, the.
18e80 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67  ** statement mig
18e90 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65  ht be re-prepare
18ea0 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
18eb0 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
18ec0 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
18ed0 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
18ee0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
18ef0 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
18f00 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
18f10 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18f20 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
18f30 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
18f40 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
18f50 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
18f60 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
18f70 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
18f80 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
18f90 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  g.** [sqlite3_pr
18fa0 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
18fb0 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
18fc0 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
18fd0 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
18fe0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
18ff0 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
19000 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e  ite3_step()], un
19010 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65  less.** as state
19020 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  d in the previou
19030 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c  s paragraph, sql
19040 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f  ite3_step() invo
19050 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  kes.** sqlite3_p
19060 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72  repare_v2() to r
19070 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65  eprepare a state
19080 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68  ment after a sch
19090 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69  ema change..*/.i
190a0 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  nt sqlite3_set_a
190b0 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c  uthorizer(.  sql
190c0 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78  ite3*,.  int (*x
190d0 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  Auth)(void*,int,
190e0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
190f0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
19100 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  ar*,const char*)
19110 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44  ,.  void *pUserD
19120 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ata.);../*.** CA
19130 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
19140 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a  er Return Codes.
19150 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
19160 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
19170 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
19180 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
19190 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e  ] must.** return
191a0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
191b0 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  OK] or one of th
191c0 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  ese two constant
191d0 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  s in order.** to
191e0 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77   signal SQLite w
191f0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
19200 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  e action is perm
19210 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a  itted.  See the.
19220 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
19230 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
19240 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74  horizer document
19250 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74  ation] for addit
19260 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
19270 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  tion..*/.#define
19280 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31   SQLITE_DENY   1
19290 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20     /* Abort the 
192a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69  SQL statement wi
192b0 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23  th an error */.#
192c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47  define SQLITE_IG
192d0 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27  NORE 2   /* Don'
192e0 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20  t allow access, 
192f0 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61  but don't genera
19300 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a  te an error */..
19310 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19320 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f  Authorizer Actio
19330 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
19340 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
19350 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74  uthorizer()] int
19360 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
19370 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
19380 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20  tion.** that is 
19390 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f  invoked to autho
193a0 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c  rize certain SQL
193b0 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f   statement actio
193c0 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ns.  The.** seco
193d0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
193e0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
193f0 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
19400 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
19410 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73  * what action is
19420 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65   being authorize
19430 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68  d.  These are th
19440 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e  e integer action
19450 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74   codes that.** t
19460 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
19470 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61  llback may be pa
19480 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ssed..**.** Thes
19490 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61  e action code va
194a0 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61  lues signify wha
194b0 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74  t kind of operat
194c0 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20  ion is to be.** 
194d0 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
194e0 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72   3rd and 4th par
194f0 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61  ameters to the a
19500 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20  uthorization.** 
19510 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
19520 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65  n will be parame
19530 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70  ters or NULL dep
19540 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20  ending on which 
19550 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65  of these.** code
19560 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  s is used as the
19570 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
19580 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61  r.  ^(The 5th pa
19590 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
195a0 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  * authorizer cal
195b0 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d  lback is the nam
195c0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
195d0 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e ("main", "temp
195e0 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61  ",.** etc.) if a
195f0 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54  pplicable.)^  ^T
19600 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72  he 6th parameter
19610 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
19620 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  er callback.** i
19630 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
19640 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69  e inner-most tri
19650 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61  gger or view tha
19660 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  t is responsible
19670 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65   for.** the acce
19680 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55  ss attempt or NU
19690 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73  LL if this acces
196a0 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72  s attempt is dir
196b0 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f  ectly from.** to
196c0 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65  p-level SQL code
196d0 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ..*/./**********
196e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
196f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
19700 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 3rd **********
19710 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 4th *********
19720 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  **/.#define SQLI
19730 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20  TE_CREATE_INDEX 
19740 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20           1   /* 
19750 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
19760 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
19770 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19780 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20  E_CREATE_TABLE  
19790 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54          2   /* T
197a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
197b0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
197c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
197d0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44  _CREATE_TEMP_IND
197e0 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e  EX     3   /* In
197f0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
19800 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
19810 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19820 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c  CREATE_TEMP_TABL
19830 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62  E     4   /* Tab
19840 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
19850 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
19860 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
19870 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47  REATE_TEMP_TRIGG
19880 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67  ER   5   /* Trig
19890 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
198a0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
198b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
198c0 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20  EATE_TEMP_VIEW  
198d0 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20      6   /* View 
198e0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
198f0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
19900 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
19910 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  ATE_TRIGGER     
19920 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65     7   /* Trigge
19930 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
19940 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
19950 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
19960 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  TE_VIEW         
19970 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    8   /* View Na
19980 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
19990 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
199a0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54  ine SQLITE_DELET
199b0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
199c0 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   9   /* Table Na
199d0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
199e0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
199f0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49  ne SQLITE_DROP_I
19a00 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31  NDEX           1
19a10 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  0   /* Index Nam
19a20 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
19a30 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
19a40 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41  e SQLITE_DROP_TA
19a50 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31  BLE           11
19a60 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
19a70 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
19a80 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19a90 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
19aa0 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20  P_INDEX      12 
19ab0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
19ac0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
19ad0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19ae0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
19af0 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20  _TABLE      13  
19b00 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
19b10 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
19b20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19b30 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
19b40 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20  TRIGGER    14   
19b50 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
19b60 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
19b70 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19b80 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56  LITE_DROP_TEMP_V
19b90 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f  IEW       15   /
19ba0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
19bb0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
19bc0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19bd0 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52  ITE_DROP_TRIGGER
19be0 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a           16   /*
19bf0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
19c00 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19c10 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19c20 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20  TE_DROP_VIEW    
19c30 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20          17   /* 
19c40 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
19c50 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
19c60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19c70 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20  E_INSERT        
19c80 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54         18   /* T
19c90 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
19ca0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
19cb0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19cc0 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
19cd0 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72        19   /* Pr
19ce0 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73  agma Name     1s
19cf0 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f  t arg or NULL */
19d00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19d10 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
19d20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62       20   /* Tab
19d30 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
19d40 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
19d50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
19d60 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
19d70 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c      21   /* NULL
19d80 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
19d90 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
19da0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
19db0 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20  ANSACTION       
19dc0 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61     22   /* Opera
19dd0 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20  tion       NULL 
19de0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
19df0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44  efine SQLITE_UPD
19e00 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
19e10 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    23   /* Table 
19e20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
19e30 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
19e40 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41  fine SQLITE_ATTA
19e50 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
19e60 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d   24   /* Filenam
19e70 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  e        NULL   
19e80 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
19e90 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43  ine SQLITE_DETAC
19ea0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
19eb0 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  25   /* Database
19ec0 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20   Name   NULL    
19ed0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
19ee0 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f  ne SQLITE_ALTER_
19ef0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
19f00 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
19f10 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d  Name   Table Nam
19f20 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
19f30 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58  e SQLITE_REINDEX
19f40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37                27
19f50 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
19f60 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
19f70 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19f80 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20   SQLITE_ANALYZE 
19f90 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20               28 
19fa0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
19fb0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
19fc0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19fd0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54  SQLITE_CREATE_VT
19fe0 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20  ABLE        29  
19ff0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1a000 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
1a010 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1a020 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c  QLITE_DROP_VTABL
1a030 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20  E          30   
1a040 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1a050 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
1a060 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1a070 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20  LITE_FUNCTION   
1a080 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f            31   /
1a090 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
1a0a0 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20    Function Name 
1a0b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1a0c0 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20  ITE_SAVEPOINT   
1a0d0 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a           32   /*
1a0e0 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
1a0f0 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20   Savepoint Name 
1a100 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1a110 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20  TE_COPY         
1a120 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20           0   /* 
1a130 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a  No longer used *
1a140 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
1a150 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50  F: Tracing And P
1a160 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f  rofiling Functio
1a170 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
1a180 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
1a190 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1a1a0 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
1a1b0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
1a1c0 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
1a1d0 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
1a1e0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
1a1f0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  s..**.** ^The ca
1a200 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1a210 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
1a220 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
1a230 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
1a240 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
1a250 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1a260 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
1a270 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
1a280 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ()]..** ^The sql
1a290 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
1a2a0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1a2b0 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65   with a UTF-8 re
1a2c0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a  ndering of the.*
1a2d0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
1a2e0 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74  text as the stat
1a2f0 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
1a300 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  ns executing..**
1a310 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71   ^(Additional sq
1a320 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
1a330 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63  llbacks might oc
1a340 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
1a350 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
1a360 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
1a370 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
1a380 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
1a390 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
1a3a0 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
1a3b0 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
1a3c0 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  rigger.)^.**.** 
1a3d0 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
1a3e0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
1a3f0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
1a400 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
1a410 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
1a420 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
1a430 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  hes.  ^The profi
1a440 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
1a450 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
1a460 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
1a470 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
1a480 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
1a490 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
1a4a0 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
1a4b0 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
1a4c0 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
1a4d0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65  callback.** time
1a4e0 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20   is in units of 
1a4f0 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77  nanoseconds, how
1a500 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74  ever the current
1a510 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
1a520 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62  ** is only capab
1a530 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  le of millisecon
1a540 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20  d resolution so 
1a550 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69  the six least si
1a560 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67  gnificant.** dig
1a570 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20  its in the time 
1a580 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e  are meaningless.
1a590 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
1a5a0 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
1a5b0 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65  ight provide gre
1a5c0 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20  ater resolution 
1a5d0 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20  on the profiler 
1a5e0 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a  callback.  The.*
1a5f0 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  * sqlite3_profil
1a600 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
1a610 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
1a620 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a  imental and is.*
1a630 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  * subject to cha
1a640 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65  nge in future ve
1a650 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1a660 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
1a670 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
1a680 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29  *, void(*xTrace)
1a690 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
1a6a0 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  r*), void*);.SQL
1a6b0 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
1a6c0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70   void *sqlite3_p
1a6d0 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
1a6e0 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
1a6f0 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
1a700 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
1a710 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
1a720 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1a730 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
1a740 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
1a750 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  The sqlite3_prog
1a760 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e  ress_handler(D,N
1a770 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20  ,X,P) interface 
1a780 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62  causes the callb
1a790 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
1a7a0 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  X to be invoked 
1a7b0 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
1a7c0 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67  ing long running
1a7d0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
1a7e0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
1a7f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1a800 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  and [sqlite3_get
1a810 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a  _table()] for.**
1a820 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a830 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d  tion D.  An exam
1a840 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
1a850 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
1a860 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
1a870 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
1a880 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
1a890 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  ** ^The paramete
1a8a0 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68  r P is passed th
1a8b0 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c  rough as the onl
1a8c0 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  y parameter to t
1a8d0 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  he .** callback 
1a8e0 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68  function X.  ^Th
1a8f0 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73  e parameter N is
1a900 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a   the number of .
1a910 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68  ** [virtual mach
1a920 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73  ine instructions
1a930 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75  ] that are evalu
1a940 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63  ated between suc
1a950 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63  cessive.** invoc
1a960 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61  ations of the ca
1a970 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20  llback X..**.** 
1a980 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70  ^Only a single p
1a990 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1a9a0 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61  may be defined a
1a9b0 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a  t one time per.*
1a9c0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1a9d0 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67  ection]; setting
1a9e0 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20   a new progress 
1a9f0 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20  handler cancels 
1aa00 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20  the.** old one. 
1aa10 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65   ^Setting parame
1aa20 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69  ter X to NULL di
1aa30 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72  sables the progr
1aa40 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
1aa50 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61  ^The progress ha
1aa60 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69  ndler is also di
1aa70 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e  sabled by settin
1aa80 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c  g N to a value l
1aa90 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a  ess.** than 1..*
1aaa0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f  *.** ^If the pro
1aab0 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72  gress callback r
1aac0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
1aad0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69   the operation i
1aae0 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64  s.** interrupted
1aaf0 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20  .  This feature 
1ab00 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69  can be used to i
1ab10 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43  mplement a.** "C
1ab20 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e  ancel" button on
1ab30 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20   a GUI progress 
1ab40 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a  dialog box..**.*
1ab50 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68  * The progress h
1ab60 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
1ab70 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
1ab80 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
1ab90 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
1aba0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1abb0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1abc0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1abd0 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  er..** Note that
1abe0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1abf0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
1ac00 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
1ac10 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
1ac20 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1ac30 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
1ac40 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
1ac50 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
1ac60 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64  raph..**.*/.void
1ac70 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
1ac80 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  s_handler(sqlite
1ac90 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28  3*, int, int(*)(
1aca0 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
1acb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1acc0 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44   Opening A New D
1acd0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
1ace0 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  on.**.** ^These 
1acf0 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e  routines open an
1ad00 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
1ad10 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65   file whose name
1ad20 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65   is given by the
1ad30 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
1ad40 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65  ument. ^The file
1ad50 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
1ad60 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1ad70 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
1ad80 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
1ad90 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1ada0 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
1adb0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
1adc0 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
1add0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1ade0 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20  . ^(A [database 
1adf0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
1ae00 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a  le is usually.**
1ae10 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
1ae20 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65  Db, even if an e
1ae30 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68  rror occurs.  Th
1ae40 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e  e only exception
1ae50 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53   is that.** if S
1ae60 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
1ae70 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
1ae80 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
1ae90 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
1aea0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20  .** a NULL will 
1aeb0 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
1aec0 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
1aed0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
1aee0 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f  e [sqlite3].** o
1aef0 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68  bject.)^ ^(If th
1af00 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1af10 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
1af20 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c  ated) successful
1af30 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c  ly, then.** [SQL
1af40 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
1af50 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
1af60 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
1af70 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e  is returned.)^ ^
1af80 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
1af90 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
1afa0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1afb0 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
1afc0 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
1afd0 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
1afe0 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
1aff0 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
1b000 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
1b010 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  lure of any.** o
1b020 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  f the sqlite3_op
1b030 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  en() routines..*
1b040 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
1b050 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74  t encoding for t
1b060 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  he database will
1b070 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20   be UTF-8 if.** 
1b080 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
1b090 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
1b0a0 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e  2() is called an
1b0b0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74  d.** UTF-16 in t
1b0c0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
1b0d0 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f  rder if sqlite3_
1b0e0 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64  open16() is used
1b0f0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20  ..**.** Whether 
1b100 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
1b110 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
1b120 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
1b130 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ces.** associate
1b140 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
1b150 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1b160 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62   handle should b
1b170 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a  e released by.**
1b180 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
1b190 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
1b1a0 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c   when it is no l
1b1b0 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a  onger required..
1b1c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1b1d0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65  3_open_v2() inte
1b1e0 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65  rface works like
1b1f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a   sqlite3_open().
1b200 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
1b210 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64  t accepts two ad
1b220 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74  ditional paramet
1b230 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ers for addition
1b240 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76  al control.** ov
1b250 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  er the new datab
1b260 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
1b270 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72   ^(The flags par
1b280 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c  ameter to.** sql
1b290 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63  ite3_open_v2() c
1b2a0 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a  an take one of.*
1b2b0 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
1b2c0 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70  three values, op
1b2d0 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
1b2e0 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  d with the .** [
1b2f0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1b300 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
1b310 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b  EN_FULLMUTEX], [
1b320 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
1b330 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64  EDCACHE],.** and
1b340 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  /or [SQLITE_OPEN
1b350 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66  _PRIVATECACHE] f
1b360 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64  lags:)^.**.** <d
1b370 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  l>.** ^(<dt>[SQL
1b380 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
1b390 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
1b3a0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1b3b0 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
1b3c0 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
1b3d0 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
1b3e0 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
1b3f0 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
1b400 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
1b410 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
1b420 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1b430 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RITE]</dt>.** <d
1b440 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1b450 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
1b460 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
1b470 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
1b480 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79   reading.** only
1b490 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
1b4a0 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
1b4b0 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
1b4c0 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74   system.  In eit
1b4d0 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  her.** case the 
1b4e0 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
1b4f0 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68  ready exist, oth
1b500 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
1b510 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
1b520 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1b530 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1b540 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
1b550 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f  E_OPEN_CREATE]</
1b560 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
1b570 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1b580 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
1b590 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69  d writing, and i
1b5a0 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20  s created if.** 
1b5b0 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
1b5c0 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
1b5d0 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
1b5e0 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
1b5f0 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
1b600 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
1b610 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
1b620 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
1b630 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
1b640 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1b650 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1b660 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
1b670 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  e.** combination
1b680 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72  s shown above or
1b690 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62   one of the comb
1b6a0 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
1b6b0 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a  bove combined.**
1b6c0 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
1b6d0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
1b6e0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
1b6f0 4c 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51  LLMUTEX],.** [SQ
1b700 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
1b710 43 41 43 48 45 5d 20 61 6e 64 2f 6f 72 20 5b 53  CACHE] and/or [S
1b720 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
1b730 54 45 43 41 43 48 45 5d 20 66 6c 61 67 73 2c 0a  TECACHE] flags,.
1b740 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
1b750 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
1b760 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
1b770 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
1b780 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
1b790 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  et, then the dat
1b7a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1b7b0 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65  .** opens in the
1b7c0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   multi-thread [t
1b7d0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
1b7e0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69  s long as the si
1b7f0 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d  ngle-thread.** m
1b800 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ode has not been
1b810 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
1b820 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
1b830 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  me.  ^If the.** 
1b840 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
1b850 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  LMUTEX] flag is 
1b860 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74  set then the dat
1b870 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1b880 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65   opens.** in the
1b890 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
1b8a0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c  eading mode] unl
1b8b0 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  ess single-threa
1b8c0 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75  d was.** previou
1b8d0 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20  sly selected at 
1b8e0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
1b8f0 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e  start-time..** ^
1b900 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
1b910 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c  _SHAREDCACHE] fl
1b920 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
1b930 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b940 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69  n to be.** eligi
1b950 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72  ble to use [shar
1b960 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20  ed cache mode], 
1b970 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
1b980 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
1b990 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
1b9a0 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73  enabled using [s
1b9b0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
1b9c0 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20  ared_cache()].  
1b9d0 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ^The.** [SQLITE_
1b9e0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
1b9f0 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
1ba00 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1ba10 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a  ection to not.**
1ba20 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20   participate in 
1ba30 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
1ba40 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69  de] even if it i
1ba50 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
1ba60 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
1ba70 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c  e is ":memory:",
1ba80 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
1ba90 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65   temporary in-me
1baa0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a  mory database.**
1bab0 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20   is created for 
1bac0 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
1bad0 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79   ^This in-memory
1bae0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76   database will v
1baf0 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68  anish when.** th
1bb00 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1bb10 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
1bb20 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
1bb30 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
1bb40 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66  t.** make use of
1bb50 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63   additional spec
1bb60 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68  ial filenames th
1bb70 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68  at begin with th
1bb80 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e  e ":" character.
1bb90 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d  .** It is recomm
1bba0 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20  ended that when 
1bbb0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  a database filen
1bbc0 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65  ame actually doe
1bbd0 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20  s begin with.** 
1bbe0 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20  a ":" character 
1bbf0 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69  you should prefi
1bc00 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77  x the filename w
1bc10 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73  ith a pathname s
1bc20 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74  uch as.** "./" t
1bc30 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74  o avoid ambiguit
1bc40 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  y..**.** ^If the
1bc50 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20   filename is an 
1bc60 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
1bc70 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
1bc80 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69  mporary.** on-di
1bc90 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
1bca0 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54   be created.  ^T
1bcb0 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
1bcc0 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
1bcd0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
1bce0 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
1bcf0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1bd00 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
1bd10 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
1bd20 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1bd30 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
1bd40 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
1bd50 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
1bd60 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
1bd70 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
1bd80 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
1bd90 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
1bda0 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
1bdb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1bdc0 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66  should use.  ^If
1bdd0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
1bde0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55  meter is.** a NU
1bdf0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
1be00 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
1be10 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1be20 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
1be30 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
1be40 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  ws users:</b>  T
1be50 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  he encoding used
1be60 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d   for the filenam
1be70 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66  e argument.** of
1be80 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1be90 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
1bea0 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54  _v2() must be UT
1beb0 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65  F-8, not whateve
1bec0 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73  r.** codepage is
1bed0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
1bee0 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63  ed.  Filenames c
1bef0 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e  ontaining intern
1bf00 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61  ational.** chara
1bf10 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f  cters must be co
1bf20 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38  nverted to UTF-8
1bf30 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e   prior to passin
1bf40 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73  g them into.** s
1bf50 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
1bf60 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1bf70 28 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ()..*/.int sqlit
1bf80 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74  e3_open(.  const
1bf90 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
1bfa0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
1bfb0 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
1bfc0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
1bfd0 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
1bfe0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
1bff0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
1c000 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a  sqlite3_open16(.
1c010 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
1c020 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
1c030 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
1c040 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
1c050 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
1c060 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
1c070 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
1c080 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1c090 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
1c0a0 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
1c0b0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
1c0c0 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
1c0d0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
1c0e0 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
1c0f0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
1c100 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
1c110 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
1c120 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
1c130 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
1c140 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
1c150 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
1c160 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
1c170 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72  ** CAPI3REF: Err
1c180 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73  or Codes And Mes
1c190 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sages.**.** ^The
1c1a0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
1c1b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
1c1c0 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
1c1d0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
1c1e0 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
1c1f0 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20  esult code] for 
1c200 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
1c210 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a  failed sqlite3_*
1c220 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73   API call.** ass
1c230 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b  ociated with a [
1c240 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c250 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72  ion]. If a prior
1c260 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64   API call failed
1c270 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74  .** but the most
1c280 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c   recent API call
1c290 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20   succeeded, the 
1c2a0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
1c2b0 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72  m.** sqlite3_err
1c2c0 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69  code() is undefi
1c2d0 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ned.  ^The sqlit
1c2e0 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
1c2f0 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ode().** interfa
1c300 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65  ce is the same e
1c310 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c  xcept that it al
1c320 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65  ways returns the
1c330 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72   .** [extended r
1c340 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e  esult code] even
1c350 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72   when extended r
1c360 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a  esult codes are.
1c370 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  ** disabled..**.
1c380 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1c390 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c  errmsg() and sql
1c3a0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20  ite3_errmsg16() 
1c3b0 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c  return English-l
1c3c0 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20  anguage.** text 
1c3d0 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
1c3e0 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74  he error, as eit
1c3f0 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
1c400 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  -16 respectively
1c410 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f  ..** ^(Memory to
1c420 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
1c430 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
1c440 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
1c450 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ally..** The app
1c460 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  lication does no
1c470 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20  t need to worry 
1c480 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68  about freeing th
1c490 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77  e result..** How
1c4a0 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20  ever, the error 
1c4b0 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20  string might be 
1c4c0 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64  overwritten or d
1c4d0 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a  eallocated by.**
1c4e0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
1c4f0 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  s to other SQLit
1c500 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63  e interface func
1c510 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57  tions.)^.**.** W
1c520 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a  hen the serializ
1c530 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
1c540 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69  de] is in use, i
1c550 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a  t might be the.*
1c560 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65  * case that a se
1c570 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72  cond error occur
1c580 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20  s on a separate 
1c590 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65  thread in betwee
1c5a0 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66  n.** the time of
1c5b0 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72   the first error
1c5c0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f   and the call to
1c5d0 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
1c5e0 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20  s..** When that 
1c5f0 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63  happens, the sec
1c600 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62  ond error will b
1c610 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65  e reported since
1c620 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66   these.** interf
1c630 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f  aces always repo
1c640 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  rt the most rece
1c650 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61  nt result.  To a
1c660 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61  void.** this, ea
1c670 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62  ch thread can ob
1c680 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75  tain exclusive u
1c690 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  se of the [datab
1c6a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1c6b0 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67  D.** by invoking
1c6c0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
1c6d0 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f  enter]([sqlite3_
1c6e0 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65  db_mutex](D)) be
1c6f0 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a  fore beginning.*
1c700 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69  * to use D and i
1c710 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
1c720 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73  _mutex_leave]([s
1c730 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
1c740 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c  (D)) after.** al
1c750 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69  l calls to the i
1c760 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64  nterfaces listed
1c770 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65   here are comple
1c780 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ted..**.** If an
1c790 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
1c7a0 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53   with SQLITE_MIS
1c7b0 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  USE, that means 
1c7c0 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
1c7d0 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63   was invoked inc
1c7e0 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  orrectly by the 
1c7f0 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e  application.  In
1c800 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a   that case, the.
1c810 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  ** error code an
1c820 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72  d message may or
1c830 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e   may not be set.
1c840 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1c850 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
1c860 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *db);.int sqlite
1c870 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
1c880 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
1c890 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1c8a0 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
1c8b0 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  te3*);.const voi
1c8c0 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
1c8d0 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  g16(sqlite3*);..
1c8e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c8f0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  SQL Statement Ob
1c900 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
1c910 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  : {prepared stat
1c920 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64  ement} {prepared
1c930 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a   statements}.**.
1c940 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
1c950 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65  f this object re
1c960 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c  presents a singl
1c970 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
1c980 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
1c990 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f  is variously kno
1c9a0 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65  wn as a "prepare
1c9b0 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  d statement" or 
1c9c0 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53  a.** "compiled S
1c9d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  QL statement" or
1c9e0 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74   simply as a "st
1c9f0 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20  atement"..**.** 
1ca00 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74  The life of a st
1ca10 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67  atement object g
1ca20 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69  oes something li
1ca30 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
1ca40 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
1ca50 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  te the object us
1ca60 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
1ca70 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20  pare_v2()] or a 
1ca80 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  related.**      
1ca90 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69  function..** <li
1caa0 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
1cab0 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   [host parameter
1cac0 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  s] using the sql
1cad0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a  ite3_bind_*().**
1cae0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
1caf0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68  ..** <li> Run th
1cb00 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67  e SQL by calling
1cb10 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1cb20 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  ] one or more ti
1cb30 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73  mes..** <li> Res
1cb40 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  et the statement
1cb50 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1cb60 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f  reset()] then go
1cb70 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f   back.**      to
1cb80 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69   step 2.  Do thi
1cb90 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74  s zero or more t
1cba0 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65  imes..** <li> De
1cbb0 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74  stroy the object
1cbc0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1cbd0 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20  finalize()]..** 
1cbe0 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65  </ol>.**.** Refe
1cbf0 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69  r to documentati
1cc00 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
1cc10 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66   methods above f
1cc20 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
1cc30 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
1cc40 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1cc50 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c  sqlite3_stmt sql
1cc60 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a  ite3_stmt;../*.*
1cc70 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
1cc80 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a  time Limits.**.*
1cc90 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61  * ^(This interfa
1cca0 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69  ce allows the si
1ccb0 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f  ze of various co
1ccc0 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c  nstructs to be l
1ccd0 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63  imited.** on a c
1cce0 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e  onnection by con
1ccf0 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20  nection basis.  
1cd00 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1cd10 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64  ter is the.** [d
1cd20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1cd30 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20  on] whose limit 
1cd40 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20  is to be set or 
1cd50 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a  queried.  The.**
1cd60 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1cd70 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  r is one of the 
1cd80 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  [limit categorie
1cd90 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  s] that define a
1cda0 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e  .** class of con
1cdb0 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69  structs to be si
1cdc0 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65  ze limited.  The
1cdd0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
1cde0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c   is the.** new l
1cdf0 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f  imit for that co
1ce00 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a  nstruct.)^.**.**
1ce10 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d   ^If the new lim
1ce20 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65  it is a negative
1ce30 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d   number, the lim
1ce40 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e  it is unchanged.
1ce50 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c  .** ^(For each l
1ce60 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51  imit category SQ
1ce70 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41  LITE_LIMIT_<i>NA
1ce80 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20  ME</i> there is 
1ce90 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  a .** [limits | 
1cea0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
1ceb0 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70  ].** set at comp
1cec0 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20  ile-time by a C 
1ced0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1cee0 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69  ro called.** [li
1cef0 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41  mits | SQLITE_MA
1cf00 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a  X_<i>NAME</i>]..
1cf10 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
1cf20 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
1cf30 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
1cf40 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65  X_".))^.** ^Atte
1cf50 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65  mpts to increase
1cf60 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69   a limit above i
1cf70 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  ts hard upper bo
1cf80 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e  und are.** silen
1cf90 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f  tly truncated to
1cfa0 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
1cfb0 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  bound..**.** ^Re
1cfc0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
1cfd0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c  her or not the l
1cfe0 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64  imit was changed
1cff0 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  , the .** [sqlit
1d000 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65  e3_limit()] inte
1d010 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
1d020 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
1d030 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e   the limit..** ^
1d040 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74  Hence, to find t
1d050 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
1d060 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68   of a limit with
1d070 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c  out changing it,
1d080 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b  .** simply invok
1d090 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  e this interface
1d0a0 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20   with the third 
1d0b0 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f  parameter set to
1d0c0 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74   -1..**.** Run-t
1d0d0 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69  ime limits are i
1d0e0 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
1d0f0 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  in applications 
1d100 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62  that manage.** b
1d110 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e  oth their own in
1d120 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20  ternal database 
1d130 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73  and also databas
1d140 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74  es that are cont
1d150 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74  rolled.** by unt
1d160 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20  rusted external 
1d170 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61  sources.  An exa
1d180 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  mple application
1d190 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77   might be a.** w
1d1a0 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20  eb browser that 
1d1b0 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61  has its own data
1d1c0 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e  bases for storin
1d1d0 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a  g history and.**
1d1e0 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
1d1f0 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  ses controlled b
1d200 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70  y JavaScript app
1d210 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f  lications downlo
1d220 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20  aded.** off the 
1d230 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69  Internet.  The i
1d240 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
1d250 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74  s can be given t
1d260 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66  he.** large, def
1d270 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61  ault limits.  Da
1d280 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20  tabases managed 
1d290 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  by external sour
1d2a0 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69  ces can.** be gi
1d2b0 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72  ven much smaller
1d2c0 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64   limits designed
1d2d0 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65   to prevent a de
1d2e0 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a  nial of service.
1d2f0 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65  ** attack.  Deve
1d300 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73  lopers might als
1d310 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68  o want to use th
1d320 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
1d330 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20  uthorizer()].** 
1d340 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72  interface to fur
1d350 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74  ther control unt
1d360 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65  rusted SQL.  The
1d370 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
1d380 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64  abase.** created
1d390 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64   by an untrusted
1d3a0 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63   script can be c
1d3b0 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74  ontained using t
1d3c0 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f  he.** [max_page_
1d3d0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e  count] [PRAGMA].
1d3e0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74  .**.** New run-t
1d3f0 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ime limit catego
1d400 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  ries may be adde
1d410 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
1d420 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ases..*/.int sql
1d430 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74  ite3_limit(sqlit
1d440 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74  e3*, int id, int
1d450 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a   newVal);../*.**
1d460 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
1d470 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f  ime Limit Catego
1d480 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ries.** KEYWORDS
1d490 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  : {limit categor
1d4a0 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67  y} {*limit categ
1d4b0 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ories}.**.** The
1d4c0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  se constants def
1d4d0 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66  ine various perf
1d4e0 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a  ormance limits.*
1d4f0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f  * that can be lo
1d500 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d  wered at run-tim
1d510 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  e using [sqlite3
1d520 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68  _limit()]..** Th
1d530 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68  e synopsis of th
1d540 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68  e meanings of th
1d550 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73  e various limits
1d560 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e   is shown below.
1d570 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69  .** Additional i
1d580 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76  nformation is av
1d590 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69  ailable at [limi
1d5a0 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53  ts | Limits in S
1d5b0 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64  QLite]..**.** <d
1d5c0 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  l>.** ^(<dt>SQLI
1d5d0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c  TE_LIMIT_LENGTH<
1d5e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1d5f0 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
1d600 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  any string or BL
1d610 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c  OB or table row,
1d620 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e   in bytes.<dd>)^
1d630 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1d640 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
1d650 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
1d660 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
1d670 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
1d680 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65  atement, in byte
1d690 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
1d6a0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1d6b0 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a  IT_COLUMN</dt>.*
1d6c0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1d6d0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
1d6e0 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64  mns in a table d
1d6f0 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20  efinition or in 
1d700 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65  the.** result se
1d710 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
1d720 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  or the maximum n
1d730 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1d740 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20   in an index.** 
1d750 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42  or in an ORDER B
1d760 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c  Y or GROUP BY cl
1d770 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ause.</dd>)^.**.
1d780 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1d790 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
1d7a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1d7b0 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
1d7c0 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
1d7d0 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
1d7e0 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
1d7f0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1d800 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
1d810 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ECT</dt>.** <dd>
1d820 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1d830 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61  er of terms in a
1d840 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
1d850 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
1d860 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1d870 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
1d880 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
1d890 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1d8a0 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
1d8b0 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
1d8c0 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
1d8d0 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
1d8e0 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
1d8f0 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d  ement.  This lim
1d900 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  it is not curren
1d910 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c  tly.** enforced,
1d920 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67   though that mig
1d930 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73  ht be added in s
1d940 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
1d950 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
1d960 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1d970 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1d980 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64  _FUNCTION_ARG</d
1d990 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1d9a0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1d9b0 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66  arguments on a f
1d9c0 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  unction.</dd>)^.
1d9d0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1d9e0 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
1d9f0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
1da00 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1da10 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
1da20 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
1da30 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
1da40 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1da50 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
1da60 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
1da70 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
1da80 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
1da90 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
1daa0 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
1dab0 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
1dac0 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
1dad0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1dae0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
1daf0 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
1db00 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65  The maximum inde
1db10 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20  x number of any 
1db20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61  [parameter] in a
1db30 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
1db40 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1db50 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
1db60 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
1db70 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1db80 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
1db90 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
1dba0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  s.</dd>)^.** </d
1dbb0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
1dbc0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
1dbd0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
1dbe0 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
1dbf0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
1dc00 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
1dc10 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
1dc20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
1dc30 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
1dc40 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
1dc50 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
1dc60 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
1dc70 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
1dc80 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
1dc90 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
1dca0 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
1dcb0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1dcc0 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
1dcd0 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
1dce0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1dcf0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
1dd00 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
1dd10 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1dd20 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
1dd30 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
1dd40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1dd50 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
1dd60 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
1dd70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1dd80 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
1dd90 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
1dda0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1ddb0 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
1ddc0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
1ddd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1dde0 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
1ddf0 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
1de00 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
1de10 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
1de20 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
1de30 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
1de40 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
1de50 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
1de60 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
1de70 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
1de80 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
1de90 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
1dea0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
1deb0 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
1dec0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1ded0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
1dee0 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
1def0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
1df00 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
1df10 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1df20 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
1df30 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
1df40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1df50 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
1df60 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
1df70 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
1df80 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
1df90 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
1dfa0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
1dfb0 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
1dfc0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
1dfd0 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
1dfe0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1dff0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1e000 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
1e010 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
1e020 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
1e030 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
1e040 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1e050 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
1e060 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
1e070 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
1e080 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a  t is less than z
1e090 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
1e0a0 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
1e0b0 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74  .** first zero t
1e0c0 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e  erminator. ^If n
1e0d0 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
1e0e0 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
1e0f0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
1e100 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73  number of  bytes
1e110 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
1e120 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73    ^When nByte is
1e130 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
1e140 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e  he.** zSql strin
1e150 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72  g ends at either
1e160 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30   the first '\000
1e170 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68  ' or '\u0000' ch
1e180 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68  aracter or.** th
1e190 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
1e1a0 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
1e1b0 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63   first. If the c
1e1c0 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74  aller knows.** t
1e1d0 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
1e1e0 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
1e1f0 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20  erminated, then 
1e200 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
1e210 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  .** performance 
1e220 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20  advantage to be 
1e230 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e  gained by passin
1e240 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
1e250 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
1e260 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d  equal to the num
1e270 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
1e280 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1e290 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
1e2a0 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
1e2b0 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a  minator bytes..*
1e2c0 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20  *.** ^If pzTail 
1e2d0 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
1e2e0 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65   *pzTail is made
1e2f0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65   to point to the
1e300 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70   first byte.** p
1e310 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ast the end of t
1e320 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61  he first SQL sta
1e330 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20  tement in zSql. 
1e340 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1e350 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20  only.** compile 
1e360 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d  the first statem
1e370 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20  ent in zSql, so 
1e380 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20  *pzTail is left 
1e390 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77  pointing to.** w
1e3a0 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f  hat remains unco
1e3b0 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a  mpiled..**.** ^*
1e3c0 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70  ppStmt is left p
1e3d0 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d  ointing to a com
1e3e0 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20  piled [prepared 
1e3f0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
1e400 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74  can be.** execut
1e410 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1e420 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20  3_step()].  ^If 
1e430 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f  there is an erro
1e440 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  r, *ppStmt is se
1e450 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e  t.** to NULL.  ^
1e460 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78  If the input tex
1e470 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51  t contains no SQ
1e480 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20  L (if the input 
1e490 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73  is an empty.** s
1e4a0 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65  tring or a comme
1e4b0 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74  nt) then *ppStmt
1e4c0 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e   is set to NULL.
1e4d0 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  .** The calling 
1e4e0 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73  procedure is res
1e4f0 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c  ponsible for del
1e500 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  eting the compil
1e510 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ed.** SQL statem
1e520 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
1e530 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61  e3_finalize()] a
1e540 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
1e550 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a  shed with it..**
1e560 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20   ppStmt may not 
1e570 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
1e580 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20  On success, the 
1e590 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1e5a0 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74  ) family of rout
1e5b0 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
1e5c0 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65  ITE_OK];.** othe
1e5d0 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
1e5e0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
1e5f0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
1e600 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1e610 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
1e620 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74  epare16_v2() int
1e630 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72  erfaces are.** r
1e640 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61  ecommended for a
1e650 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e  ll new programs.
1e660 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69   The two older i
1e670 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65  nterfaces are re
1e680 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61  tained.** for ba
1e690 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1e6a0 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72  ility, but their
1e6b0 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61   use is discoura
1e6c0 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ged..** ^In the 
1e6d0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c  "v2" interfaces,
1e6e0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
1e6f0 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20  atement.** that 
1e700 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65  is returned (the
1e710 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
1e720 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73  object) contains
1e730 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
1e740 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
1e750 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73  ext. This causes
1e760 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
1e770 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ep()] interface 
1e780 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66  to.** behave dif
1e790 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65  ferently in thre
1e7a0 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e ways:.**.** <o
1e7b0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  l>.** <li>.** ^I
1e7c0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  f the database s
1e7d0 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69  chema changes, i
1e7e0 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e  nstead of return
1e7f0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  ing [SQLITE_SCHE
1e800 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77  MA] as it.** alw
1e810 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20  ays used to do, 
1e820 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1e830 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61   will automatica
1e840 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68  lly recompile th
1e850 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  e SQL.** stateme
1e860 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75  nt and try to ru
1e870 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a 2a 20 3c  n it again..** <
1e880 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
1e890 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f  ** ^When an erro
1e8a0 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74  r occurs, [sqlit
1e8b0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
1e8c0 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68  return one of th
1e8d0 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65  e detailed.** [e
1e8e0 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b  rror codes] or [
1e8f0 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
1e900 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67  odes].  ^The leg
1e910 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73  acy behavior was
1e920 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65   that.** [sqlite
1e930 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20  3_step()] would 
1e940 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65  only return a ge
1e950 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52  neric [SQLITE_ER
1e960 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65  ROR] result code
1e970 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c  .** and the appl
1e980 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61  ication would ha
1e990 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63  ve to make a sec
1e9a0 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ond call to [sql
1e9b0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a  ite3_reset()].**
1e9c0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
1e9d0 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
1e9e0 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72   cause of the pr
1e9f0 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20  oblem. With the 
1ea00 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20  "v2" prepare.** 
1ea10 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
1ea20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f  underlying reaso
1ea30 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20  n for the error 
1ea40 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
1ea50 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69  diately..** </li
1ea60 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
1ea70 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63  ^If the specific
1ea80 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20   value bound to 
1ea90 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73  [parameter | hos
1eaa0 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  t parameter] in 
1eab0 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c  the .** WHERE cl
1eac0 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75  ause might influ
1ead0 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20  ence the choice 
1eae0 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f  of query plan fo
1eaf0 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a  r a statement,.*
1eb00 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65  * then the state
1eb10 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74  ment will be aut
1eb20 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
1eb30 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65  piled, as if the
1eb40 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20  re had been .** 
1eb50 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c  a schema change,
1eb60 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b   on the first  [
1eb70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1eb80 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  call following a
1eb90 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20  ny change.** to 
1eba0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
1ebb0 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67  d_text | binding
1ebc0 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61  s] of that [para
1ebd0 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65  meter]. .** ^The
1ebe0 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
1ebf0 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20  of WHERE-clause 
1ec00 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68  [parameter] migh
1ec10 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
1ec20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75  .** choice of qu
1ec30 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20  ery plan if the 
1ec40 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
1ec50 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20   left-hand side 
1ec60 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f  of a [LIKE].** o
1ec70 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  r [GLOB] operato
1ec80 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61  r or if the para
1ec90 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65  meter is compare
1eca0 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20  d to an indexed 
1ecb0 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68  column.** and th
1ecc0 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  e [SQLITE_ENABLE
1ecd0 5f 53 54 41 54 32 5d 20 63 6f 6d 70 69 6c 65 2d  _STAT2] compile-
1ece0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
1ecf0 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 0a  nabled..** the .
1ed00 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c  ** </li>.** </ol
1ed10 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  >.*/.int sqlite3
1ed20 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
1ed30 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1ed40 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1ed50 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1ed60 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1ed70 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1ed80 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
1ed90 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
1eda0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
1edb0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
1edc0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
1edd0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
1ede0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
1edf0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
1ee00 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
1ee10 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
1ee20 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
1ee30 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
1ee40 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
1ee50 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
1ee60 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a  te3_prepare_v2(.
1ee70 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1ee80 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1ee90 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
1eea0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1eeb0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
1eec0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
1eed0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
1eee0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
1eef0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
1ef00 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
1ef10 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
1ef20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
1ef30 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
1ef40 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
1ef50 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1ef60 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
1ef70 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
1ef80 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
1ef90 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
1efa0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1efb0 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
1efc0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
1efd0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
1efe0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1eff0 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
1f000 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1f010 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
1f020 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1f030 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1f040 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1f050 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1f060 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1f070 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1f080 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1f090 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1f0a0 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
1f0b0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1f0c0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
1f0d0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
1f0e0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1f0f0 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
1f100 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1f110 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1f120 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1f130 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
1f140 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1f150 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
1f160 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1f170 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1f180 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1f190 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1f1a0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1f1b0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1f1c0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1f1d0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1f1e0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1f1f0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1f200 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1f210 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1f220 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
1f230 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1f240 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65  trieving Stateme
1f250 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68  nt SQL.**.** ^Th
1f260 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
1f270 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72   be used to retr
1f280 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70  ieve a saved cop
1f290 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61  y of the origina
1f2a0 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73  l.** SQL text us
1f2b0 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b  ed to create a [
1f2c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1f2d0 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74  nt] if that stat
1f2e0 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d  ement was.** com
1f2f0 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
1f300 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
1f310 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
1f320 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1f330 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  v2()]..*/.const 
1f340 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71  char *sqlite3_sq
1f350 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
1f360 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
1f370 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
1f380 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
1f390 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68  tement Writes Th
1f3a0 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a  e Database.**.**
1f3b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
1f3c0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69  mt_readonly(X) i
1f3d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1f3e0 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
1f3f0 20 69 66 20 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79   if .** and only
1f400 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   if the [prepare
1f410 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 69  d statement] X i
1f420 73 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63  s makes no direc
1f430 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20  t changes to.** 
1f440 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
1f450 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
1f460 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
1f470 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  t [application-d
1f480 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
1f490 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72  ions] or.** [vir
1f4a0 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67  tual tables] mig
1f4b0 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ht change the da
1f4c0 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c  tabase indirectl
1f4d0 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65  y as a side effe
1f4e0 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65  ct.  .** ^(For e
1f4f0 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70  xample, if an ap
1f500 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
1f510 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76  s a function "ev
1f520 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63  al()" that .** c
1f530 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78  alls [sqlite3_ex
1f540 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  ec()], then the 
1f550 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74  following SQL st
1f560 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a  atement would.**
1f570 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
1f580 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67  base file throug
1f590 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a  h side-effects:.
1f5a0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1f5b0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45  e><pre>.**    SE
1f5c0 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54  LECT eval('DELET
1f5d0 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d  E FROM t1') FROM
1f5e0 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f   t2;.** </pre></
1f5f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1f600 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68  * But because th
1f610 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
1f620 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68  ment does not ch
1f630 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
1f640 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74  e file.** direct
1f650 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  ly, sqlite3_stmt
1f660 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c  _readonly() woul
1f670 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74  d still return t
1f680 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72  rue.)^.**.** ^Tr
1f690 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
1f6a0 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63  l statements suc
1f6b0 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43  h as [BEGIN], [C
1f6c0 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43  OMMIT], [ROLLBAC
1f6d0 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e  K],.** [SAVEPOIN
1f6e0 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45  T], and [RELEASE
1f6f0 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f  ] cause sqlite3_
1f700 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
1f710 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a  to return true,.
1f720 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61  ** since the sta
1f730 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76  tements themselv
1f740 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c  es do not actual
1f750 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  ly modify the da
1f760 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61  tabase but.** ra
1f770 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f  ther they contro
1f780 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20  l the timing of 
1f790 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65  when other state
1f7a0 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65  ments modify the
1f7b0 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20   .** database.  
1f7c0 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e  ^The [ATTACH] an
1f7d0 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65  d [DETACH] state
1f7e0 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65  ments also cause
1f7f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  .** sqlite3_stmt
1f800 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
1f810 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65  eturn true since
1f820 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74  , while those st
1f830 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e  atements.** chan
1f840 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  ge the configura
1f850 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61  tion of a databa
1f860 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74  se connection, t
1f870 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20  hey do not make 
1f880 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74  .** changes to t
1f890 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
1f8a0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  e database files
1f8b0 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74   on disk..*/.int
1f8c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
1f8d0 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73  adonly(sqlite3_s
1f8e0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
1f8f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79  .** CAPI3REF: Dy
1f900 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20  namically Typed 
1f910 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  Value Object.** 
1f920 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65  KEYWORDS: {prote
1f930 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1f940 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64  ue} {unprotected
1f950 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a   sqlite3_value}.
1f960 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
1f970 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61  s the sqlite3_va
1f980 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65  lue object to re
1f990 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75  present all valu
1f9a0 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  es.** that can b
1f9b0 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61  e stored in a da
1f9c0 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51  tabase table. SQ
1f9d0 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
1f9e0 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20  c typing.** for 
1f9f0 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74  the values it st
1fa00 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73  ores.  ^Values s
1fa10 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33  tored in sqlite3
1fa20 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a  _value objects.*
1fa30 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72  * can be integer
1fa40 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  s, floating poin
1fa50 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
1fa60 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
1fa70 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69  L..**.** An sqli
1fa80 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1fa90 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22   may be either "
1faa0 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75  protected" or "u
1fab0 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20  nprotected"..** 
1fac0 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20  Some interfaces 
1fad0 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63  require a protec
1fae0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1faf0 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66  e.  Other interf
1fb00 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63  aces.** will acc
1fb10 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f  ept either a pro
1fb20 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70  tected or an unp
1fb30 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1fb40 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79  _value..** Every
1fb50 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
1fb60 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f  accepts sqlite3_
1fb70 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20  value arguments 
1fb80 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65  specifies.** whe
1fb90 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72  ther or not it r
1fba0 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63  equires a protec
1fbb0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1fbc0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72  e..**.** The ter
1fbd0 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61  ms "protected" a
1fbe0 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  nd "unprotected"
1fbf0 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65   refer to whethe
1fc00 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  r or not.** a mu
1fc10 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20  tex is held.  A 
1fc20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
1fc30 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
1fc40 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
1fc50 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
1fc60 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
1fc70 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
1fc80 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
1fc90 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
1fca0 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
1fcb0 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
1fcc0 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
1fcd0 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
1fce0 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
1fcf0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
1fd00 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
1fd10 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
1fd20 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
1fd30 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
1fd40 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
1fd50 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
1fd60 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
1fd70 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
1fd80 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
1fd90 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
1fda0 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
1fdb0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
1fdc0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
1fdd0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
1fde0 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
1fdf0 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
1fe00 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
1fe10 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
1fe20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
1fe30 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
1fe40 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
1fe50 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
1fe60 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
1fe70 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
1fe80 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
1fe90 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
1fea0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1feb0 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
1fec0 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
1fed0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
1fee0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
1fef0 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
1ff00 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
1ff10 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
1ff20 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
1ff30 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
1ff40 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
1ff50 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
1ff60 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
1ff70 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1ff80 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
1ff90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
1ffa0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
1ffb0 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
1ffc0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
1ffd0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1ffe0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
1fff0 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
20000 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
20010 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
20020 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
20030 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
20040 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
20050 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
20060 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
20070 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
20080 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
20090 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
200a0 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
200b0 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
200c0 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
200d0 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
200e0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
200f0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
20100 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
20110 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
20120 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
20130 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
20140 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
20150 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
20160 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
20170 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
20180 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
20190 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
201a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
201b0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
201c0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
201d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
201e0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
201f0 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
20200 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
20210 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
20220 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
20230 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
20240 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
20250 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
20260 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
20270 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
20280 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
20290 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
202a0 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
202b0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
202c0 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
202d0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
202e0 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
202f0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
20300 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
20310 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
20320 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
20330 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
20340 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
20350 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
20360 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
20370 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
20380 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
20390 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
203a0 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
203b0 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
203c0 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
203d0 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a  r binding}.**.**
203e0 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74   ^(In the SQL st
203f0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70  atement text inp
20400 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
20410 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
20420 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
20430 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
20440 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
20450 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74  [parameter] that
20460 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20   matches one of 
20470 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d  following.** tem
20480 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  plates:.**.** <u
20490 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
204a0 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
204b0 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
204c0 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
204d0 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
204e0 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70  *.** In the temp
204f0 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e  lates above, NNN
20500 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69   represents an i
20510 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
20520 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65  ** and VVV repre
20530 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75  sents an alphanu
20540 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72  meric identifier
20550 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  .)^  ^The values
20560 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72   of these.** par
20570 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
20580 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
20590 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22  eter names" or "
205a0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29  SQL parameters")
205b0 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75  .** can be set u
205c0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
205d0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
205e0 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  es defined here.
205f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
20600 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
20610 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
20620 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61  () routines is a
20630 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  lways.** a point
20640 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
20650 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20  e3_stmt] object 
20660 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a  returned from.**
20670 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20680 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
20690 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ariants..**.** ^
206a0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
206b0 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
206c0 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
206d0 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
206e0 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  .** ^The leftmos
206f0 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
20700 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
20710 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61  1.  ^When the sa
20720 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20  me named.** SQL 
20730 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
20740 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
20750 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
20760 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
20770 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
20780 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
20790 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
207a0 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65  ce..** ^The inde
207b0 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
207c0 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
207d0 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
207e0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
207f0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
20800 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
20810 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65  ired.  ^The inde
20820 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
20830 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
20840 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
20850 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75  ** ^The NNN valu
20860 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
20870 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c  n 1 and the [sql
20880 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
20890 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49   parameter [SQLI
208a0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
208b0 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75  E_NUMBER] (defau
208c0 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
208d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
208e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
208f0 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
20900 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
20910 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73  .**.** ^(In thos
20920 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  e routines that 
20930 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
20940 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
20950 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
20960 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
20970 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
20980 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
20990 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
209a0 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74  number of <u>byt
209b0 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61  es</u> in the va
209c0 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  lue, not the num
209d0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
209e0 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.)^.** ^If the 
209f0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
20a00 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
20a10 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
20a20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65  string is.** the
20a30 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
20a40 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
20a50 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
20a60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66  ..**.** ^The fif
20a70 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
20a80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
20a90 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  (), sqlite3_bind
20aa0 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20  _text(), and.** 
20ab0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
20ac0 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72  t16() is a destr
20ad0 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69  uctor used to di
20ae0 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
20af0 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61  B or.** string a
20b00 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20  fter SQLite has 
20b10 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
20b20 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  .  ^The destruct
20b30 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20  or is called.** 
20b40 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
20b50 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  e BLOB or string
20b60 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c   even if the cal
20b70 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  l to sqlite3_bin
20b80 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c  d_blob(),.** sql
20b90 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
20ba0 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  , or sqlite3_bin
20bb0 64 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c 73  d_text16() fails
20bc0 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .  .** ^If the f
20bd0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73  ifth argument is
20be0 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20  .** the special 
20bf0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54  value [SQLITE_ST
20c00 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69  ATIC], then SQLi
20c10 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
20c20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  the.** informati
20c30 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c  on is in static,
20c40 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65   unmanaged space
20c50 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65   and does not ne
20c60 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a  ed to be freed..
20c70 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
20c80 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68   argument has th
20c90 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  e value [SQLITE_
20ca0 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e  TRANSIENT], then
20cb0 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
20cc0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
20cd0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74   copy of the dat
20ce0 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  a immediately, b
20cf0 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c  efore.** the sql
20d00 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
20d10 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a  utine returns..*
20d20 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
20d30 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
20d40 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20  ) routine binds 
20d50 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68  a BLOB of length
20d60 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69   N that.** is fi
20d70 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73  lled with zeroes
20d80 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75  .  ^A zeroblob u
20d90 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75  ses a fixed amou
20da0 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20  nt of memory.** 
20db0 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72  (just an integer
20dc0 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a   to hold its siz
20dd0 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62  e) while it is b
20de0 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a  eing processed..
20df0 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65  ** Zeroblobs are
20e00 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72   intended to ser
20e10 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65  ve as placeholde
20e20 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f  rs for BLOBs who
20e30 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73  se.** content is
20e40 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75   later written u
20e50 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
20e60 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63  _blob_open | inc
20e70 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f  remental BLOB I/
20e80 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20  O] routines..** 
20e90 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75  ^A negative valu
20ea0 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c  e for the zerobl
20eb0 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20  ob results in a 
20ec0 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
20ed0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20  ..**.** ^If any 
20ee0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  of the sqlite3_b
20ef0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
20f00 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68   are called with
20f10 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
20f20 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  ** for the [prep
20f30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
20f40 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72  or with a prepar
20f50 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72  ed statement for
20f60 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74   which.** [sqlit
20f70 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62  e3_step()] has b
20f80 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20  een called more 
20f90 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73  recently than [s
20fa0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
20fb0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c  .** then the cal
20fc0 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  l will return [S
20fd0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
20fe0 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62  If any sqlite3_b
20ff0 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ind_().** routin
21000 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70  e is passed a [p
21010 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21020 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e  t] that has been
21030 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a   finalized, the.
21040 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  ** result is und
21050 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
21060 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
21070 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65  ** ^Bindings are
21080 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
21090 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
210a0 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
210b0 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d  * ^Unbound param
210c0 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70  eters are interp
210d0 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a  reted as NULL..*
210e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
210f0 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65  3_bind_* routine
21100 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
21110 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
21120 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20  or an.** [error 
21130 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e  code] if anythin
21140 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
21150 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d   ^[SQLITE_RANGE]
21160 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
21170 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  the parameter.**
21180 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
21190 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54   range.  ^[SQLIT
211a0 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
211b0 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29  rned if malloc()
211c0 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65   fails..**.** Se
211d0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
211e0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
211f0 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  count()],.** [sq
21200 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
21210 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
21220 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
21230 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
21240 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
21250 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c  e3_bind_blob(sql
21260 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
21270 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
21280 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
21290 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
212a0 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71  3_bind_double(sq
212b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
212c0 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73  , double);.int s
212d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28  qlite3_bind_int(
212e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
212f0 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  nt, int);.int sq
21300 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34  lite3_bind_int64
21310 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
21320 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  int, sqlite3_int
21330 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  64);.int sqlite3
21340 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74  _bind_null(sqlit
21350 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
21360 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
21370 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
21380 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
21390 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  char*, int n, vo
213a0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
213b0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
213c0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
213d0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
213e0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
213f0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
21400 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76  t sqlite3_bind_v
21410 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
21420 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73  t*, int, const s
21430 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
21440 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
21450 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
21460 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
21470 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
21480 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
21490 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a   SQL Parameters.
214a0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
214b0 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ine can be used 
214c0 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
214d0 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d  er of [SQL param
214e0 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b  eters].** in a [
214f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21500 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65  nt].  SQL parame
21510 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20  ters are tokens 
21520 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22  of the.** form "
21530 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41  ?", "?NNN", ":AA
21540 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22  A", "$AAA", or "
21550 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65  @AAA" that serve
21560 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64   as.** placehold
21570 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74  ers for values t
21580 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33  hat are [sqlite3
21590 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75  _bind_blob | bou
215a0 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61  nd].** to the pa
215b0 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61  rameters at a la
215c0 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ter time..**.** 
215d0 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61  ^(This routine a
215e0 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20  ctually returns 
215f0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
21600 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d   largest (rightm
21610 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ost).** paramete
21620 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73  r. For all forms
21630 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68   except ?NNN, th
21640 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f  is will correspo
21650 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d  nd to the.** num
21660 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61  ber of unique pa
21670 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61  rameters.  If pa
21680 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
21690 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73  ?NNN form are us
216a0 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79  ed,.** there may
216b0 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20   be gaps in the 
216c0 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  list.)^.**.** Se
216d0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
216e0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
216f0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
21700 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
21710 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
21720 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
21730 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
21740 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
21750 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
21760 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c  ameter_count(sql
21770 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
21780 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
21790 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72  me Of A Host Par
217a0 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68  ameter.**.** ^Th
217b0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  e sqlite3_bind_p
217c0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c  arameter_name(P,
217d0 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  N) interface ret
217e0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  urns.** the name
217f0 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51   of the N-th [SQ
21800 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  L parameter] in 
21810 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
21820 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
21830 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20  (SQL parameters 
21840 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e  of the form "?NN
21850 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
21860 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
21870 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20  .** have a name 
21880 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72  which is the str
21890 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  ing "?NNN" or ":
218a0 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
218b0 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70  r "$AAA".** resp
218c0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20  ectively..** In 
218d0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
218e0 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20   initial ":" or 
218f0 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f  "$" or "@" or "?
21900 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64  ".** is included
21910 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   as part of the 
21920 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61  name.)^.** ^Para
21930 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
21940 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61  rm "?" without a
21950 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67   following integ
21960 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a  er have no name.
21970 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72  ** and are refer
21980 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c  red to as "namel
21990 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f  ess" or "anonymo
219a0 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a  us parameters"..
219b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
219c0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
219d0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
219e0 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20  1, not 0..**.** 
219f0 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20  ^If the value N 
21a00 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  is out of range 
21a10 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70  or if the N-th p
21a20 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e  arameter is.** n
21a30 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55  ameless, then NU
21a40 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  LL is returned. 
21a50 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
21a60 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61  tring is.** alwa
21a70 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f  ys in UTF-8 enco
21a80 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ding even if the
21a90 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
21aa0 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   was.** original
21ab0 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ly specified as 
21ac0 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74  UTF-16 in [sqlit
21ad0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
21ae0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  or.** [sqlite3_p
21af0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
21b00 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
21b10 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
21b20 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
21b30 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
21b40 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
21b50 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
21b60 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
21b70 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
21b80 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
21b90 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  *sqlite3_bind_pa
21ba0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c  rameter_name(sql
21bb0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
21bc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
21bd0 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61  F: Index Of A Pa
21be0 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47  rameter With A G
21bf0 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20  iven Name.**.** 
21c00 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65  ^Return the inde
21c10 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
21c20 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20  meter given its 
21c30 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69  name.  ^The.** i
21c40 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72  ndex value retur
21c50 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20  ned is suitable 
21c60 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73  for use as the s
21c70 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74  econd.** paramet
21c80 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
21c90 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
21ca0 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65  _bind()].  ^A ze
21cb0 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ro.** is returne
21cc0 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67  d if no matching
21cd0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f   parameter is fo
21ce0 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  und.  ^The param
21cf0 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73  eter.** name mus
21d00 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54  t be given in UT
21d10 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20  F-8 even if the 
21d20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
21d30 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72  nt.** was prepar
21d40 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74  ed from UTF-16 t
21d50 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ext using [sqlit
21d60 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
21d70 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
21d80 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
21d90 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
21da0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
21db0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
21dc0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
21dd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
21de0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
21df0 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
21e00 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
21e10 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65  ter_index(sqlite
21e20 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63  3_stmt*, const c
21e30 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a  har *zName);../*
21e40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
21e50 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73  set All Bindings
21e60 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53   On A Prepared S
21e70 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e  tatement.**.** ^
21e80 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20  Contrary to the 
21e90 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e  intuition of man
21ea0 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  y, [sqlite3_rese
21eb0 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65  t()] does not re
21ec0 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  set.** the [sqli
21ed0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
21ee0 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b  bindings] on a [
21ef0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21f00 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69  nt]..** ^Use thi
21f10 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73  s routine to res
21f20 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61  et all host para
21f30 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a  meters to NULL..
21f40 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
21f50 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
21f60 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
21f70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
21f80 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
21f90 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
21fa0 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
21fb0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
21fc0 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
21fd0 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
21fe0 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  by the.** [prepa
21ff0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
22000 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
22010 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74  turns 0 if pStmt
22020 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74   is an SQL.** st
22030 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65  atement that doe
22040 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74  s not return dat
22050 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61  a (for example a
22060 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a  n [UPDATE])..**.
22070 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
22080 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
22090 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ()].*/.int sqlit
220a0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
220b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
220c0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
220d0 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
220e0 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
220f0 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  Set.**.** ^These
22100 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
22110 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
22120 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c  ed to a particul
22130 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20  ar column.** in 
22140 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
22150 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
22160 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71  tement.  ^The sq
22170 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
22180 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
22190 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
221a0 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
221b0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
221c0 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
221d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
221e0 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
221f0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
22200 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
22210 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
22220 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
22230 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61  er is the [prepa
22240 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
22250 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  * that implement
22260 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  s the [SELECT] s
22270 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73  tatement. ^The s
22280 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
22290 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  is the.** column
222a0 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c   number.  ^The l
222b0 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  eftmost column i
222c0 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  s number 0..**.*
222d0 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
222e0 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
222f0 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
22300 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72  ther the [prepar
22310 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
22320 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79   is destroyed by
22330 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
22340 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
22350 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a  he next call to.
22360 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
22370 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
22380 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
22390 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  6() on the same 
223a0 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  column..**.** ^I
223b0 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
223c0 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
223d0 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
223e0 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
223f0 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
22400 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
22410 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
22420 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
22430 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
22440 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
22450 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
22460 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  f a result colum
22470 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  n is the value o
22480 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73  f the "AS" claus
22490 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f  e for.** that co
224a0 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69  lumn, if there i
224b0 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20  s an AS clause. 
224c0 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
224d0 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65  AS clause.** the
224e0 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
224f0 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70  e column is unsp
22500 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20  ecified and may 
22510 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f  change from.** o
22520 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ne release of SQ
22530 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74  Lite to the next
22540 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
22550 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
22560 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
22570 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73  t*, int N);.cons
22580 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
22590 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71  column_name16(sq
225a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
225b0 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
225c0 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20  3REF: Source Of 
225d0 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20  Data In A Query 
225e0 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  Result.**.** ^Th
225f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f  ese routines pro
22600 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20  vide a means to 
22610 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61  determine the da
22620 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
22630 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75  nd.** table colu
22640 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f  mn that is the o
22650 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69  rigin of a parti
22660 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c  cular result col
22670 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43  umn in.** [SELEC
22680 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  T] statement..**
22690 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
226a0 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61  e database or ta
226b0 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61  ble or column ca
226c0 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  n be returned as
226d0 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46  .** either a UTF
226e0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  -8 or UTF-16 str
226f0 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61  ing.  ^The _data
22700 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
22710 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
22720 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
22730 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
22740 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
22750 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
22760 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
22770 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
22780 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  olumn name..** ^
22790 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
227a0 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ing is valid unt
227b0 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  il the [prepared
227c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
227d0 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e  estroyed.** usin
227e0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
227f0 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
22800 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
22810 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
22820 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20  d.** again in a 
22830 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69  different encodi
22840 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ng..**.** ^The n
22850 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72  ames returned ar
22860 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75  e the original u
22870 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20  n-aliased names 
22880 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  of the.** databa
22890 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63  se, table, and c
228a0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  olumn..**.** ^Th
228b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
228c0 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
228d0 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61  aces is a [prepa
228e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
228f0 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
22900 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
22910 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
22920 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
22930 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  mn returned by.*
22940 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c  * the statement,
22950 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
22960 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
22970 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
22980 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75  e left-most colu
22990 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66  mn is column 0 f
229a0 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  or these routine
229b0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  s..**.** ^If the
229c0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
229d0 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74  rned by the stat
229e0 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72  ement is an expr
229f0 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62  ession or.** sub
22a00 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74  query and is not
22a10 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c   a column value,
22a20 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65   then all of the
22a30 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
22a40 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54  urn.** NULL.  ^T
22a50 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67  hese routine mig
22a60 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e  ht also return N
22a70 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20  ULL if a memory 
22a80 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
22a90 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74  .** occurs.  ^Ot
22aa0 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65  herwise, they re
22ab0 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  turn the name of
22ac0 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61   the attached da
22ad0 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a  tabase, table,.*
22ae0 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74  * or column that
22af0 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f   query result co
22b00 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74  lumn was extract
22b10 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  ed from..**.** ^
22b20 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65  As with all othe
22b30 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74  r SQLite APIs, t
22b40 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73  hose whose names
22b50 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72   end with "16" r
22b60 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20  eturn.** UTF-16 
22b70 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20  encoded strings 
22b80 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75  and the other fu
22b90 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55  nctions return U
22ba0 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  TF-8..**.** ^The
22bb0 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
22bc0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
22bd0 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
22be0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
22bf0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
22c00 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
22c10 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f  A] C-preprocesso
22c20 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20  r symbol..**.** 
22c30 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
22c40 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
22c50 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65  or more of these
22c60 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73   routines agains
22c70 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72  t the same.** pr
22c80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22c90 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74   and column at t
22ca0 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
22cb0 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
22cc0 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  e.** undefined..
22cd0 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
22ce0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
22cf0 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  l one or more.**
22d00 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
22d10 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c  _database_name |
22d20 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61   column metadata
22d30 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
22d40 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72  for the same [pr
22d50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22d60 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c  ] and result col
22d70 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61  umn.** at the sa
22d80 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
22d90 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
22da0 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  efined..*/.const
22db0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
22dc0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
22dd0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
22de0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
22df0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
22e00 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
22e10 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
22e20 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
22e30 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
22e40 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
22e50 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
22e60 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
22e70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
22e80 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
22e90 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
22ea0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
22eb0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
22ec0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
22ed0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
22ee0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
22ef0 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
22f00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
22f10 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
22f20 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
22f30 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
22f40 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
22f50 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61  ^(The first para
22f60 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
22f70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
22f80 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
22f90 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
22fa0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
22fb0 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
22fc0 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
22fd0 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
22fe0 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
22ff0 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
23000 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
23010 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
23020 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
23030 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
23040 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
23050 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  mn is returned.)
23060 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ^  ^If the Nth c
23070 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
23080 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
23090 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
230a0 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
230b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
230c0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68  returned..** ^Th
230d0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
230e0 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
230f0 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a  8 encoded..**.**
23100 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
23110 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
23120 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
23130 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
23140 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
23150 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
23160 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
23170 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
23180 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
23190 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
231a0 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
231b0 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
231c0 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
231d0 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
231e0 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
231f0 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
23200 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
23210 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
23220 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
23230 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  =0).)^.**.** ^SQ
23240 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
23250 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
23260 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63  g.  ^So just bec
23270 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
23280 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
23290 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
232a0 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
232b0 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
232c0 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
232d0 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
232e0 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
232f0 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
23300 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
23310 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
23320 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
23330 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79  not static.  ^Ty
23340 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
23350 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
23360 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
23370 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
23380 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
23390 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
233a0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
233b0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
233c0 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
233d0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
233e0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
233f0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
23400 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
23410 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
23420 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65  PI3REF: Evaluate
23430 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
23440 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20  t.**.** After a 
23450 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
23460 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72  ent] has been pr
23470 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74  epared using eit
23480 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
23490 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
234a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
234b0 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  e16_v2()] or one
234c0 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
234d0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
234e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
234f0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
23500 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
23510 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
23520 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
23530 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
23540 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
23550 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
23560 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
23570 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
23580 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
23590 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
235a0 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
235b0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
235c0 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
235d0 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69  the newer "v2" i
235e0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c  nterface.** [sql
235f0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
23600 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
23610 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
23620 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
23630 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
23640 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
23650 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
23660 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
23670 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
23680 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65  ** new "v2" inte
23690 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
236a0 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
236b0 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
236c0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
236d0 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
236e0 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
236f0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ted..**.** ^In t
23700 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
23710 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
23720 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
23730 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
23740 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
23750 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
23760 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
23770 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
23780 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68  ISUSE]..** ^With
23790 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
237a0 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
237b0 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
237c0 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
237d0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
237e0 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
237f0 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
23800 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53  .** ^[SQLITE_BUS
23810 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
23820 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
23830 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
23840 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
23850 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
23860 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
23870 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73   job.  ^If the s
23880 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43  tatement is a [C
23890 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63  OMMIT].** or occ
238a0 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
238b0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
238c0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
238d0 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
238e0 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
238f0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
23900 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d  s not a [COMMIT]
23910 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
23920 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74  in a.** explicit
23930 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
23940 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
23950 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
23960 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
23970 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
23980 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
23990 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
239a0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
239b0 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
239c0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
239d0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
239e0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
239f0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
23a00 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
23a10 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
23a20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
23a30 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
23a40 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
23a50 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
23a60 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
23a70 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
23a80 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
23a90 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
23aa0 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
23ab0 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
23ac0 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
23ad0 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
23ae0 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
23af0 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
23b00 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
23b10 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
23b20 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
23b30 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
23b40 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
23b50 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
23b60 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
23b70 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
23b80 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
23b90 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
23ba0 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
23bb0 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
23bc0 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
23bd0 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
23be0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
23bf0 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
23c00 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
23c10 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
23c20 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
23c30 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
23c40 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
23c50 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
23c60 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
23c70 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
23c80 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
23c90 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
23ca0 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
23cb0 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
23cc0 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
23cd0 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
23ce0 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
23cf0 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
23d00 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
23d10 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
23d20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
23d30 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
23d40 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
23d50 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
23d60 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
23d70 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
23d80 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
23d90 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
23da0 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
23db0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
23dc0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
23dd0 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
23de0 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
23df0 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
23e00 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
23e10 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
23e20 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
23e30 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
23e40 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
23e50 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
23e60 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
23e70 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
23e80 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
23e90 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
23ea0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
23eb0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
23ec0 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
23ed0 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
23ee0 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
23ef0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
23f00 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
23f10 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
23f20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
23f30 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
23f40 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
23f50 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
23f60 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
23f70 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
23f80 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  1, a call to.** 
23f90 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
23fa0 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61  ] was required a
23fb0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65  fter sqlite3_ste
23fc0 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79  p() returned any
23fd0 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74  thing.** other t
23fe0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
23ff0 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73   before any subs
24000 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
24010 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n of.** sqlite3_
24020 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65  step().  Failure
24030 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72   to reset the pr
24040 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24050 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
24060 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75  te3_reset()] wou
24070 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ld result in an 
24080 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
24090 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73  return from.** s
240a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
240b0 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f  But after versio
240c0 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69  n 3.6.23.1, sqli
240d0 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e  te3_step() began
240e0 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** calling [sql
240f0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75  ite3_reset()] au
24100 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
24110 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65  his circumstance
24120 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20   rather.** than 
24130 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
24140 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73  E_MISUSE].  This
24150 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72   is not consider
24160 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69  ed a compatibili
24170 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61  ty.** break beca
24180 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74  use any applicat
24190 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65  ion that ever re
241a0 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45  ceives an SQLITE
241b0 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a  _MISUSE error.**
241c0 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65   is broken by de
241d0 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b  finition.  The [
241e0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
241f0 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  RESET] compile-t
24200 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61  ime option.** ca
24210 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73  n be used to res
24220 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20  tore the legacy 
24230 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
24240 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
24250 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
24260 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
24270 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
24280 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
24290 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
242a0 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
242b0 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
242c0 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
242d0 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
242e0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
242f0 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
24300 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
24310 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
24320 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
24330 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
24340 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
24350 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
24360 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
24370 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
24380 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
24390 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
243a0 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
243b0 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
243c0 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
243d0 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
243e0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
243f0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
24400 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
24410 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
24420 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
24430 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
24440 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
24450 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
24460 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
24470 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
24480 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
24490 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
244a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
244b0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
244c0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
244d0 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
244e0 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
244f0 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
24500 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
24510 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
24520 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
24530 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
24540 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
24550 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
24560 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
24570 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
24580 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
24590 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20  esult set.**.** 
245a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
245b0 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
245c0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
245d0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
245e0 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
245f0 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
24600 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
24610 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24620 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
24630 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
24640 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
24650 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
24660 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
24670 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
24680 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
24690 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
246a0 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
246b0 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
246c0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
246d0 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
246e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
246f0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
24700 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
24710 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
24720 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
24730 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
24740 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
24750 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  t()].*/.int sqli
24760 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73  te3_data_count(s
24770 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
24780 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
24790 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61  3REF: Fundamenta
247a0 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b  l Datatypes.** K
247b0 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
247c0 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65  TEXT.**.** ^(Eve
247d0 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69  ry value in SQLi
247e0 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69  te has one of fi
247f0 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64  ve fundamental d
24800 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20  atatypes:.**.** 
24810 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  <ul>.** <li> 64-
24820 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
24830 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  er.** <li> 64-bi
24840 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20  t IEEE floating 
24850 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20  point number.** 
24860 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c  <li> string.** <
24870 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e  li> BLOB.** <li>
24880 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e   NULL.** </ul>)^
24890 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
248a0 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73  stants are codes
248b0 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f   for each of tho
248c0 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20  se types..**.** 
248d0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51  Note that the SQ
248e0 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61  LITE_TEXT consta
248f0 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64  nt was also used
24900 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   in SQLite versi
24910 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f  on 2.** for a co
24920 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65  mpletely differe
24930 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66  nt meaning.  Sof
24940 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73  tware that links
24950 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a   against both.**
24960 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
24970 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  2 and SQLite ver
24980 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73  sion 3 should us
24990 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20  e SQLITE3_TEXT, 
249a0 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45  not.** SQLITE_TE
249b0 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  XT..*/.#define S
249c0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31  QLITE_INTEGER  1
249d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
249e0 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69  FLOAT    2.#defi
249f0 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20  ne SQLITE_BLOB  
24a00 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
24a10 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23  ITE_NULL     5.#
24a20 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  ifdef SQLITE_TEX
24a30 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  T.# undef SQLITE
24a40 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65  _TEXT.#else.# de
24a50 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54  fine SQLITE_TEXT
24a60 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64       3.#endif.#d
24a70 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45  efine SQLITE3_TE
24a80 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20  XT     3../*.** 
24a90 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
24aa0 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51   Values From A Q
24ab0 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  uery.** KEYWORDS
24ac0 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  : {column access
24ad0 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
24ae0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
24af0 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c   form the "resul
24b00 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 63 65  t set" interface
24b10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
24b20 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69  outines return i
24b30 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
24b40 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e   a single column
24b50 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
24b60 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66  ** result row of
24b70 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65   a query.  ^In e
24b80 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69  very case the fi
24b90 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
24ba0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
24bb0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
24bc0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73  atement] that is
24bd0 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64   being evaluated
24be0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
24bf0 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tmt*].** that wa
24c00 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
24c10 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
24c20 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
24c30 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a   its variants).*
24c40 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  * and the second
24c50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
24c60 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
24c70 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69  lumn for which i
24c80 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68  nformation.** sh
24c90 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
24ca0 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  . ^The leftmost 
24cb0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
24cc0 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65  sult set has the
24cd0 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68   index 0..** ^Th
24ce0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
24cf0 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
24d00 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  t can be determi
24d10 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ned using.** [sq
24d20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
24d30 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  nt()]..**.** If 
24d40 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
24d50 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65  t does not curre
24d60 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20  ntly point to a 
24d70 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66  valid row, or if
24d80 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69   the.** column i
24d90 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
24da0 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74  ange, the result
24db0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
24dc0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
24dd0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c   may only be cal
24de0 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73  led when the mos
24df0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
24e00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
24e10 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
24e20 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61  d [SQLITE_ROW] a
24e30 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73  nd neither.** [s
24e40 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
24e50 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  nor [sqlite3_fin
24e60 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65  alize()] have be
24e70 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71  en called subseq
24e80 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e  uently..** If an
24e90 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
24ea0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61  nes are called a
24eb0 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  fter [sqlite3_re
24ec0 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
24ed0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
24ee0 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69  ] or after [sqli
24ef0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
24f00 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65  returned.** some
24f10 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
24f20 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
24f30 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
24f40 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
24f50 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
24f60 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
24f70 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
24f80 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
24f90 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
24fa0 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72   a different thr
24fb0 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66  ead while any of
24fc0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
24fd0 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20  ** are pending, 
24fe0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
24ff0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
25000 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
25010 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
25020 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
25030 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
25040 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
25050 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  pe code] for the
25060 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79   initial data ty
25070 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  pe.** of the res
25080 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68  ult column.  ^Th
25090 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65  e returned value
250a0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
250b0 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20  TE_INTEGER],.** 
250c0 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
250d0 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b  [SQLITE_TEXT], [
250e0 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72  SQLITE_BLOB], or
250f0 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20   [SQLITE_NULL]. 
25100 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   The value.** re
25110 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
25120 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
25130 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66  is only meaningf
25140 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a  ul if no type.**
25150 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76   conversions hav
25160 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65  e occurred as de
25170 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20  scribed below.  
25180 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e  After a type con
25190 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20  version,.** the 
251a0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
251b0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
251c0 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66  _type() is undef
251d0 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a  ined.  Future.**
251e0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
251f0 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74  ite may change t
25200 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
25210 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
25220 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  pe().** followin
25230 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  g a type convers
25240 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ion..**.** ^If t
25250 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
25260 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72  LOB or UTF-8 str
25270 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
25280 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
25290 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  s().** routine r
252a0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
252b0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
252c0 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
252d0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
252e0 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36  sult is a UTF-16
252f0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
25300 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
25310 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  es() converts.**
25320 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
25330 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65  TF-8 and then re
25340 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
25350 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
25360 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
25370 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
25380 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
25390 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73  umn_bytes() uses
253a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
253b0 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
253c0 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
253d0 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  o a UTF-8 string
253e0 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
253f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
25400 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
25410 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
25420 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
25430 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
25440 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72  mn_bytes() retur
25450 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
25460 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
25470 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31   a BLOB or UTF-1
25480 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  6 string then th
25490 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
254a0 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f  _bytes16().** ro
254b0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
254c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
254d0 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
254e0 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
254f0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
25500 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74   UTF-8 string, t
25510 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
25520 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e  mn_bytes16() con
25530 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
25540 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e  ing to UTF-16 an
25550 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
25560 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
25570 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
25580 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
25590 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
255a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
255b0 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b  es16() uses.** [
255c0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
255d0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
255e0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
255f0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64  TF-16 string and
25600 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
25610 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
25620 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
25630 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
25640 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
25650 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
25660 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73  ytes16() returns
25670 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   zero..**.** ^Th
25680 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
25690 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
256a0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
256b0 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  d .** [sqlite3_c
256c0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
256d0 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20   do not include 
256e0 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
256f0 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a  tors at the end.
25700 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
25710 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a  .  ^For clarity:
25720 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75   the values retu
25730 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
25740 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
25750 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
25760 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
25770 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65  )] are the numbe
25780 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
25790 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
257a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
257b0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
257c0 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e   ^Strings return
257d0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
257e0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20  lumn_text() and 
257f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
25800 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e  ext16(),.** even
25810 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20   empty strings, 
25820 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20  are always zero 
25830 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
25840 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
25850 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
25860 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
25870 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
25880 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  LOB is a NULL po
25890 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
258a0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
258b0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
258c0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
258d0 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
258e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
258f0 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75  e] object.  An u
25900 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
25910 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a  e3_value object.
25920 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ** may only be u
25930 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  sed with [sqlite
25940 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20  3_bind_value()] 
25950 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  and [sqlite3_res
25960 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ult_value()]..**
25970 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65   If the [unprote
25980 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
25990 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  ue] object retur
259a0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
259b0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
259c0 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e  )] is used in an
259d0 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63  y other way, inc
259e0 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20  luding calls.** 
259f0 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
25a00 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
25a10 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  int()], [sqlite3
25a20 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
25a30 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
25a40 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74  alue_bytes()], t
25a50 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
25a60 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
25a70 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
25a80 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63  nes attempt to c
25a90 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
25aa0 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61   where appropria
25ab0 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61  te.  ^For.** exa
25ac0 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74  mple, if the int
25ad0 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
25ae0 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e  tion is FLOAT an
25af0 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a  d a text result.
25b00 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c  ** is requested,
25b10 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
25b20 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  tf()] is used in
25b30 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66  ternally to perf
25b40 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65  orm the.** conve
25b50 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61  rsion automatica
25b60 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c  lly.  ^(The foll
25b70 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61  owing table deta
25b80 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ils the conversi
25b90 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ons.** that are 
25ba0 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c  applied:.**.** <
25bb0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
25bc0 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
25bd0 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e  >.** <tr><th> In
25be0 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c  ternal<br>Type <
25bf0 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72  th> Requested<br
25c00 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76  >Type <th>  Conv
25c10 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  ersion.**.** <tr
25c20 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
25c30 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
25c40 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a  d> Result is 0.*
25c50 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
25c60 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
25c70 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
25c80 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64  s 0.0.** <tr><td
25c90 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
25ca0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52    TEXT    <td> R
25cb0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
25cc0 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
25cd0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
25ce0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
25cf0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
25d00 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
25d10 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
25d20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
25d30 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65  onvert from inte
25d40 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20  ger to float.** 
25d50 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
25d60 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
25d70 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
25d80 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74  ering of the int
25d90 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
25da0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
25db0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
25dc0 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54  me as INTEGER->T
25dd0 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
25de0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e   FLOAT   <td> IN
25df0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
25e00 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20  vert from float 
25e10 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  to integer.** <t
25e20 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
25e30 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
25e40 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
25e50 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74  ing of the float
25e60 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
25e70 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  OAT   <td>   BLO
25e80 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
25e90 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a  s FLOAT->TEXT.**
25ea0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
25eb0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
25ec0 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28    <td> Use atoi(
25ed0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
25ee0 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  EXT    <td>  FLO
25ef0 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61  AT    <td> Use a
25f00 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
25f10 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
25f20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e    BLOB    <td> N
25f30 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e  o change.** <tr>
25f40 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
25f50 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
25f60 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
25f70 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28  T then use atoi(
25f80 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
25f90 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  LOB    <td>  FLO
25fa0 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
25fb0 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
25fc0 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  use atof().** <t
25fd0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
25fe0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
25ff0 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74  td> Add a zero t
26000 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65  erminator if nee
26010 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  ded.** </table>.
26020 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
26030 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  )^.**.** The tab
26040 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72  le above makes r
26050 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e  eference to stan
26060 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66  dard C library f
26070 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a  unctions atoi().
26080 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20  ** and atof().  
26090 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20  SQLite does not 
260a0 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65  really use these
260b0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20   functions.  It 
260c0 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65  has its.** own e
260d0 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e  quivalent intern
260e0 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68  al routines.  Th
260f0 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f  e atoi() and ato
26100 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  f() names are.**
26110 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62   used in the tab
26120 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61  le for brevity a
26130 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20  nd because they 
26140 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20  are familiar to 
26150 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61  most.** C progra
26160 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  mmers..**.** Not
26170 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65  e that when type
26180 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63   conversions occ
26190 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ur, pointers ret
261a0 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a  urned by prior.*
261b0 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
261c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
261d0 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  , sqlite3_column
261e0 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a  _text(), and/or.
261f0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
26200 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62  n_text16() may b
26210 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
26220 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  * Type conversio
26230 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69  ns and pointer i
26240 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67  nvalidations mig
26250 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  ht occur.** in t
26260 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73  he following cas
26270 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
26280 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
26290 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20  al content is a 
262a0 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33  BLOB and sqlite3
262b0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
262c0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
262d0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
262e0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20  ) is called.  A 
262f0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20  zero-terminator 
26300 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65  might.**      ne
26310 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74  ed to be added t
26320 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c  o the string.</l
26330 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
26340 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
26350 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64  s UTF-8 text and
26360 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26370 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20  bytes16() or.** 
26380 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
26390 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
263a0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
263b0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
263c0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
263d0 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a  o UTF-16.</li>.*
263e0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
263f0 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
26400 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71  F-16 text and sq
26410 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
26420 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  es() or.**      
26430 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
26440 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  ext() is called.
26450 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
26460 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
26470 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38  **      to UTF-8
26480 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  .</li>.** </ul>.
26490 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f  **.** ^Conversio
264a0 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31  ns between UTF-1
264b0 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65  6be and UTF-16le
264c0 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65   are always done
264d0 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f   in place and do
264e0 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61  .** not invalida
264f0 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74  te a prior point
26500 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  er, though of co
26510 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74  urse the content
26520 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a   of the buffer.*
26530 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72  * that the prior
26540 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e   pointer referen
26550 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65  ces will have be
26560 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
26570 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
26580 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
26590 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
265a0 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
265b0 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20  , but sometimes 
265c0 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  they.** are not 
265d0 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
265e0 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
265f0 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
26600 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a  nvalidated..**.*
26610 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64  * The safest and
26620 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65   easiest to reme
26630 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74  mber policy is t
26640 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72  o invoke these r
26650 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e  outines.** in on
26660 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
26670 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ng ways:.**.** <
26680 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
26690 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
266a0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
266b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
266c0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
266d0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
266e0 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
266f0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
26700 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
26710 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
26720 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
26730 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
26740 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
26750 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  16()</li>.** </u
26760 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
26770 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
26780 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
26790 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
267a0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
267b0 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
267c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
267d0 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
267e0 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
267f0 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
26800 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
26810 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
26820 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
26830 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
26840 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
26850 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
26860 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
26870 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
26880 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
26890 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
268a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
268b0 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
268c0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
268d0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
268e0 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
268f0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
26900 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
26910 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
26920 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
26930 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ytes()..**.** ^T
26940 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
26950 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
26960 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
26970 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
26980 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
26990 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
269a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
269b0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
269c0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
269d0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
269e0 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20  s called.  ^The 
269f0 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65  memory space use
26a00 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67  d to hold string
26a10 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69  s.** and BLOBs i
26a20 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69  s freed automati
26a30 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f  cally.  Do <b>no
26a40 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70  t</b> pass the p
26a50 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
26a60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
26a70 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  umn_blob()], [sq
26a80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
26a90 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a  t()], etc. into.
26aa0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
26ab0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ()]..**.** ^(If 
26ac0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
26ad0 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
26ae0 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c   during the eval
26af0 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a  uation of any.**
26b00 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
26b10 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61  es, a default va
26b20 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
26b30 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61    The default va
26b40 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  lue.** is either
26b50 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20   the integer 0, 
26b60 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  the floating poi
26b70 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f  nt number 0.0, o
26b80 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
26b90 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ter.  Subsequent
26ba0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
26bb0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69  e3_errcode()] wi
26bc0 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  ll return.** [SQ
26bd0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a  LITE_NOMEM].)^.*
26be0 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
26bf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
26c00 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
26c10 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
26c20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
26c30 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ytes(sqlite3_stm
26c40 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
26c50 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
26c60 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  n_bytes16(sqlite
26c70 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
26c80 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  l);.double sqlit
26c90 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
26ca0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
26cb0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
26cc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
26cd0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
26ce0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
26cf0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
26d00 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73  3_column_int64(s
26d10 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
26d20 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75  t iCol);.const u
26d30 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
26d40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
26d50 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
26d60 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
26d70 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
26d80 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71  column_text16(sq
26d90 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
26da0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
26db0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
26dc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
26dd0 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
26de0 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33  3_value *sqlite3
26df0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71  _column_value(sq
26e00 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
26e10 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   iCol);../*.** C
26e20 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79  API3REF: Destroy
26e30 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
26e40 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ement Object.**.
26e50 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
26e60 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74  finalize() funct
26e70 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
26e80 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61   delete a [prepa
26e90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
26ea0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
26eb0 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
26ec0 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65  n of the stateme
26ed0 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e  nt encountered n
26ee0 6f 20 65 72 72 6f 72 73 20 6f 72 0a 2a 2a 20 6f  o errors or.** o
26ef0 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  r if the stateme
26f00 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e  nt is never been
26f10 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e   evaluated, then
26f20 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
26f30 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53  e() returns.** S
26f40 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74  QLITE_OK.  ^If t
26f50 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
26f60 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61  valuation of sta
26f70 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c  tement S failed,
26f80 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
26f90 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74  _finalize(S) ret
26fa0 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72  urns the appropr
26fb0 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
26fc0 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
26fd0 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a  d error code]..*
26fe0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26ff0 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f  3_finalize(S) ro
27000 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c  utine can be cal
27010 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  led at any point
27020 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c   during.** the l
27030 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72  ife cycle of [pr
27040 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27050 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73  ] S:.** before s
27060 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76  tatement S is ev
27070 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66  er evaluated, af
27080 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f  ter.** one or mo
27090 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  re calls to [sql
270a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f  ite3_reset()], o
270b0 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c  r after any call
270c0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
270d0 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65  step()] regardle
270e0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
270f0 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65   not the stateme
27100 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65  nt has.** comple
27110 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a  ted execution..*
27120 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73  *.** ^Invoking s
27130 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
27140 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) on a NULL poin
27150 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ter is a harmles
27160 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54  s no-op..**.** T
27170 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
27180 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65  ust finalize eve
27190 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ry [prepared sta
271a0 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72  tement] in order
271b0 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73   to avoid.** res
271c0 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74  ource leaks.  It
271d0 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65   is a grievous e
271e0 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  rror for the app
271f0 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20  lication to try 
27200 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70  to use.** a prep
27210 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
27220 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
27230 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79   finalized.  Any
27240 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72   use of a prepar
27250 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
27260 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
27270 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20  n finalized can 
27280 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
27290 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73  ned and.** undes
272a0 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20  irable behavior 
272b0 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74  such as segfault
272c0 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75  s and heap corru
272d0 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ption..*/.int sq
272e0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73  lite3_finalize(s
272f0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
27300 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
27310 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72  3REF: Reset A Pr
27320 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
27330 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
27340 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  e sqlite3_reset(
27350 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
27360 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20  lled to reset a 
27370 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27380 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62  ent].** object b
27390 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
273a0 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20  al state, ready 
273b0 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65  to be re-execute
273c0 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73  d..** ^Any SQL s
273d0 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c  tatement variabl
273e0 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75  es that had valu
273f0 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d  es bound to them
27400 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73   using.** the [s
27410 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
27420 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
27430 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20  *() API] retain 
27440 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a  their values..**
27450 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c   Use [sqlite3_cl
27460 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20  ear_bindings()] 
27470 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e  to reset the bin
27480 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dings..**.** ^Th
27490 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
274a0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
274b0 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61  esets the [prepa
274c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
274d0 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20  .** back to the 
274e0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73  beginning of its
274f0 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20   program..**.** 
27500 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
27510 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
27520 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
27530 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
27540 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
27550 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
27560 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _ROW] or [SQLITE
27570 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66  _DONE],.** or if
27580 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
27590 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66  )] has never bef
275a0 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ore been called 
275b0 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73  on S,.** then [s
275c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
275d0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
275e0 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  _OK]..**.** ^If 
275f0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
27600 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
27610 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
27620 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
27630 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69  tatement] S indi
27640 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20  cated an error, 
27650 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  then.** [sqlite3
27660 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
27670 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  ns an appropriat
27680 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  e [error code]..
27690 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
276a0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
276b0 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74  terface does not
276c0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
276d0 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71  es.** of any [sq
276e0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
276f0 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65  bindings] on the
27700 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
27710 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20  ment] S..*/.int 
27720 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
27730 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
27740 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
27750 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
27760 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
27770 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
27780 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
27790 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a  ation routines}.
277a0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
277b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
277c0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a  d SQL function}.
277d0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
277e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
277f0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d  d SQL functions}
27800 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  .**.** ^These fu
27810 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74  nctions (collect
27820 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22  ively known as "
27830 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
27840 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20  n routines").** 
27850 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
27860 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
27870 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74   aggregates or t
27880 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62  o redefine the b
27890 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78  ehavior.** of ex
278a0 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74  isting SQL funct
278b0 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
278c0 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69  es.  The only di
278d0 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65  fferences betwee
278e0 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69  n.** these routi
278f0 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74  nes are the text
27900 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74   encoding expect
27910 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 74 68  ed for.** the th
27920 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
27930 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20  er (the name of 
27940 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  the function bei
27950 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61  ng created).** a
27960 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  nd the presence 
27970 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20  or absence of a 
27980 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
27990 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ack for.** the a
279a0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
279b0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
279c0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
279d0 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
279e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
279f0 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
27a00 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
27a10 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e   to be added.  ^
27a20 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  If an applicatio
27a30 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  n uses more than
27a40 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
27a50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e   connection then
27a60 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
27a70 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
27a80 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
27a90 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61  .** to each data
27aa0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
27ab0 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
27ac0 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  * ^The second pa
27ad0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
27ae0 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
27af0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
27b00 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
27b10 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e  fined.  ^The len
27b20 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
27b30 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
27b40 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46  5 bytes in a UTF
27b50 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61  -8.** representa
27b60 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20  tion, exclusive 
27b70 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  of the zero-term
27b80 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74  inator.  ^Note t
27b90 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  hat the name.** 
27ba0 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
27bb0 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20  in UTF-8 bytes, 
27bc0 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e  not characters n
27bd0 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e  or UTF-16 bytes.
27be0 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d    .** ^Any attem
27bf0 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
27c00 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
27c10 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
27c20 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
27c30 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69  LITE_MISUSE] bei
27c40 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
27c50 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  ** ^The third pa
27c60 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a  rameter (nArg).*
27c70 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
27c80 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
27c90 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
27ca0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
27cb0 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68  te takes. ^If th
27cc0 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
27cd0 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  -1, then the SQL
27ce0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
27cf0 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
27d00 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
27d10 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65   arguments betwe
27d20 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d  en 0 and the lim
27d30 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71  it.** set by [sq
27d40 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
27d50 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
27d60 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74  ION_ARG]).  If t
27d70 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
27d80 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
27d90 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72  an -1 or greater
27da0 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74   than 127 then t
27db0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  he behavior is.*
27dc0 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
27dd0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
27de0 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
27df0 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
27e00 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
27e10 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
27e20 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
27e30 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
27e40 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
27e50 65 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20  ers.  Every SQL 
27e60 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
27e70 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  ntation must be 
27e80 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  able to work.** 
27e90 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d  with UTF-8, UTF-
27ea0 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62  16le, or UTF-16b
27eb0 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70  e.  But some imp
27ec0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
27ed0 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69   be.** more effi
27ee0 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65  cient with one e
27ef0 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f  ncoding than ano
27f00 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69  ther.  ^An appli
27f10 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e  cation may.** in
27f20 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  voke sqlite3_cre
27f30 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f  ate_function() o
27f40 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
27f50 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75  _function16() mu
27f60 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20  ltiple.** times 
27f70 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75  with the same fu
27f80 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20  nction but with 
27f90 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73  different values
27fa0 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a   of eTextRep..**
27fb0 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
27fc0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
27fd0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
27fe0 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
27ff0 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
28000 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
28010 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
28020 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
28030 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
28040 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69  n..** If there i
28050 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  s only a single 
28060 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
28070 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61  hich does not ca
28080 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20  re what text.** 
28090 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
280a0 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  , then the fourt
280b0 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  h argument shoul
280c0 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59  d be [SQLITE_ANY
280d0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  ]..**.** ^(The f
280e0 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
280f0 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
28100 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
28110 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
28120 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
28130 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
28140 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
28150 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
28160 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a  er_data()].)^.**
28170 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20  .** ^The sixth, 
28180 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68  seventh and eigh
28190 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78  th parameters, x
281a0 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20  Func, xStep and 
281b0 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70  xFinal, are.** p
281c0 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e  ointers to C-lan
281d0 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20  guage functions 
281e0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
281f0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
28200 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e  or.** aggregate.
28210 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66   ^A scalar SQL f
28220 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
28230 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
28240 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a  on of the xFunc.
28250 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  ** callback only
28260 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  ; NULL pointers 
28270 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61  must be passed a
28280 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20  s the xStep and 
28290 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65  xFinal.** parame
282a0 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67  ters. ^An aggreg
282b0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
282c0 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
282d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78  lementation of x
282e0 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
282f0 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e  al and NULL poin
28300 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73  ter must be pass
28310 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54  ed for xFunc. ^T
28320 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73  o delete an exis
28330 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63  ting.** SQL func
28340 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
28350 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69  e, pass NULL poi
28360 6e 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72  ners for all thr
28370 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63  ee function.** c
28380 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
28390 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70  ^(If the ninth p
283a0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
283b0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
283c0 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  ion_v2() is not 
283d0 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74  NULL,.** then it
283e0 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66   is destructor f
283f0 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
28400 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
28410 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63   .** The destruc
28420 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  tor is invoked w
28430 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
28440 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74   is deleted, eit
28450 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20  her by being.** 
28460 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68  overloaded or wh
28470 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
28480 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
28490 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73  s.)^.** ^The des
284a0 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20  tructor is also 
284b0 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63  invoked if the c
284c0 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
284d0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
284e0 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  n_v2() fails..**
284f0 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72   ^When the destr
28500 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f  uctor callback o
28510 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61  f the tenth para
28520 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64  meter is invoked
28530 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65  , it.** is passe
28540 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  d a single argum
28550 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63  ent which is a c
28560 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69  opy of the appli
28570 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20  cation data .** 
28580 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61  pointer which wa
28590 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61  s the fifth para
285a0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
285b0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
285c0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  _v2()..**.** ^It
285d0 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
285e0 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70   register multip
285f0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
28600 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  ns of the same.*
28610 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68  * functions with
28620 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
28630 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64  ut with either d
28640 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73  iffering numbers
28650 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73   of.** arguments
28660 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72   or differing pr
28670 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
28680 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65  odings.  ^SQLite
28690 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65   will use.** the
286a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
286b0 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  that most closel
286c0 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
286d0 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
286e0 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
286f0 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63  s used.  ^A func
28700 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
28710 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e  ion with a non-n
28720 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20  egative.** nArg 
28730 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
28740 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e  etter match than
28750 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   a function impl
28760 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a  ementation with.
28770 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41  ** a negative nA
28780 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  rg.  ^A function
28790 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65   where the prefe
287a0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
287b0 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68  ng.** matches th
287c0 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64  e database encod
287d0 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a  ing is a better.
287e0 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  ** match than a 
287f0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
28800 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  he encoding is d
28810 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e  ifferent.  .** ^
28820 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
28830 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
28840 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77  fference is betw
28850 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20  een UTF16le and 
28860 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20  UTF16be.** is a 
28870 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61  closer match tha
28880 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
28890 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
288a0 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a  difference is.**
288b0 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e   between UTF8 an
288c0 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e  d UTF16..**.** ^
288d0 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  Built-in functio
288e0 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f  ns may be overlo
288f0 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c  aded by new appl
28900 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
28910 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  functions..**.**
28920 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
28930 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
28940 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  n is permitted t
28950 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  o call other.** 
28960 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
28970 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63  s.  However, suc
28980 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74  h calls must not
28990 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61  .** close the da
289a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
289b0 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f  n nor finalize o
289c0 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  r reset the prep
289d0 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
289e0 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66  t in which the f
289f0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
28a00 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ng..*/.int sqlit
28a10 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
28a20 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
28a30 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
28a40 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
28a50 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
28a60 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
28a70 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
28a80 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
28a90 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
28aa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
28ab0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
28ac0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
28ad0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
28ae0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
28af0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
28b00 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e  _context*).);.in
28b10 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
28b20 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73  _function16(.  s
28b30 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
28b40 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74  nst void *zFunct
28b50 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
28b60 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
28b70 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
28b80 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
28b90 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
28ba0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
28bb0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
28bc0 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
28bd0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
28be0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
28bf0 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
28c00 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
28c10 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
28c20 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
28c30 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
28c40 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
28c50 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
28c60 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
28c70 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
28c80 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
28c90 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
28ca0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
28cb0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
28cc0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
28cd0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
28ce0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
28cf0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
28d00 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
28d10 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20  te3_context*),. 
28d20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
28d30 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  (void*).);../*.*
28d40 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
28d50 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
28d60 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
28d70 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
28d80 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
28d90 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
28da0 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
28db0 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
28dc0 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
28dd0 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
28de0 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
28df0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
28e00 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
28e10 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
28e20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
28e30 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
28e40 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
28e50 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
28e60 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
28e70 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
28e80 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73         5    /* s
28e90 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
28ea0 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23  nction only */.#
28eb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
28ec0 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
28ed0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
28ee0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
28ef0 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
28f00 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
28f10 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
28f20 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
28f30 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
28f40 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
28f50 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
28f60 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
28f70 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
28f80 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
28f90 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
28fa0 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
28fb0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
28fc0 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
28fd0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
28fe0 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
28ff0 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
29000 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c  nctions.  To hel
29010 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70  p encourage peop
29020 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75  le to avoid.** u
29030 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74  sing these funct
29040 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74  ions, we are not
29050 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79   going to tell y
29060 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  ou what they do.
29070 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
29080 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
29090 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  ED.SQLITE_DEPREC
290a0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
290b0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
290c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
290d0 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
290e0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
290f0 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
29100 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
29110 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
29120 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
29130 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
29140 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
29150 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
29160 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
29170 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
29180 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
29190 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
291a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
291b0 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
291c0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
291d0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
291e0 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
291f0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
29200 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f  e3_int64,int),vo
29210 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
29220 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  4);.#endif../*.*
29230 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
29240 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69  ining SQL Functi
29250 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c  on Parameter Val
29260 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  ues.**.** The C-
29270 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
29280 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
29290 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
292a0 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
292b0 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
292c0 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
292d0 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
292e0 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
292f0 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
29300 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
29310 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
29320 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
29330 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
29340 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
29350 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
29360 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
29370 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
29380 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
29390 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
293a0 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
293b0 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
293c0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
293d0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
293e0 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70  es..** The 3rd p
293f0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
29400 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
29410 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
29420 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
29430 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
29440 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
29450 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
29460 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
29470 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
29480 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
29490 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
294a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
294b0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
294c0 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
294d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
294e0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
294f0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
29500 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
29510 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
29520 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
29530 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
29540 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
29550 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
29560 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
29570 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
29580 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
29590 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
295a0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  or..**.** ^These
295b0 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
295c0 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
295d0 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
295e0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
295f0 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
29600 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69  hat  these routi
29610 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
29620 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
29630 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
29640 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  ct.** pointer in
29650 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
29660 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
29670 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
29680 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
29690 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
296a0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
296b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74  () interface ext
296c0 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73  racts a UTF-16 s
296d0 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
296e0 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
296f0 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
29700 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  chine.  ^The.** 
29710 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
29720 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
29730 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
29740 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
29750 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d  .** extract UTF-
29760 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69  16 strings as bi
29770 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74  g-endian and lit
29780 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  tle-endian respe
29790 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ctively..**.** ^
297a0 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  (The sqlite3_val
297b0 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
297c0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
297d0 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a  mpts to apply.**
297e0 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74   numeric affinit
297f0 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20  y to the value. 
29800 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74   This means that
29810 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a   an attempt is.*
29820 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72  * made to conver
29830 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61  t the value to a
29840 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f  n integer or flo
29850 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66  ating point.  If
29860 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65  .** such a conve
29870 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c  rsion is possibl
29880 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f  e without loss o
29890 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69  f information (i
298a0 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73  n other.** words
298b0 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  , if the value i
298c0 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20  s a string that 
298d0 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d  looks like a num
298e0 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ber).** then the
298f0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
29900 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72  erformed.  Other
29910 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69  wise no conversi
29920 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68  on occurs..** Th
29930 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  e [SQLITE_INTEGE
29940 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66  R | datatype] af
29950 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ter conversion i
29960 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
29970 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
29980 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
29990 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
299a0 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
299b0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
299c0 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
299d0 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
299e0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
299f0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
29a00 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
29a10 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
29a20 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
29a30 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
29a40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
29a50 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
29a60 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
29a70 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
29a80 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
29a90 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
29aa0 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  text16()]..**.**
29ab0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
29ac0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
29ad0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
29ae0 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
29af0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
29b00 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
29b10 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
29b20 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e  rameters..*/.con
29b30 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
29b40 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69  _value_blob(sqli
29b50 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
29b60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
29b70 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c  ytes(sqlite3_val
29b80 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
29b90 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
29ba0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
29bb0 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
29bc0 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
29bd0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
29be0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
29bf0 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
29c00 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  e*);.sqlite3_int
29c10 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64 sqlite3_value
29c20 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76  _int64(sqlite3_v
29c30 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e  alue*);.const un
29c40 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
29c50 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
29c60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
29c70 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
29c80 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
29c90 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
29ca0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
29cb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
29cc0 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  t16le(sqlite3_va
29cd0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
29ce0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
29cf0 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
29d00 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
29d10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
29d20 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
29d30 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
29d40 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
29d50 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
29d60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
29d70 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65  EF: Obtain Aggre
29d80 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f  gate Function Co
29d90 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c  ntext.**.** Impl
29da0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61  ementations of a
29db0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
29dc0 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a  ctions use this.
29dd0 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c  ** routine to al
29de0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f  locate memory fo
29df0 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
29e00 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  state..**.** ^Th
29e10 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65  e first time the
29e20 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
29e30 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
29e40 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
29e50 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74  d .** for a part
29e60 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65  icular aggregate
29e70 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74   function, SQLit
29e80 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e  e.** allocates N
29e90 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f   of memory, zero
29ea0 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f  es out that memo
29eb0 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
29ec0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
29ed0 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20  the new memory. 
29ee0 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ^On second and s
29ef0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
29f00 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  to.** sqlite3_ag
29f10 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
29f20 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61  ) for the same a
29f30 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
29f40 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74  n instance,.** t
29f50 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69  he same buffer i
29f60 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c  s returned.  Sql
29f70 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
29f80 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d  ontext() is norm
29f90 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f  ally.** called o
29fa0 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76  nce for each inv
29fb0 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ocation of the x
29fc0 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e  Step callback an
29fd0 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61  d then one.** la
29fe0 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65  st time when the
29ff0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
2a000 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28   is invoked.  ^(
2a010 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74  When no rows mat
2a020 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61  ch.** an aggrega
2a030 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53  te query, the xS
2a040 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f  tep() callback o
2a050 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  f the aggregate 
2a060 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c  function.** impl
2a070 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65  ementation is ne
2a080 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78  ver called and x
2a090 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65  Final() is calle
2a0a0 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a  d exactly once..
2a0b0 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65  ** In those case
2a0c0 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  s, sqlite3_aggre
2a0d0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d  gate_context() m
2a0e0 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66  ight be called f
2a0f0 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  or the.** first 
2a100 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e  time from within
2a110 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a   xFinal().)^.**.
2a120 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2a130 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2a140 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72  t(C,N) routine r
2a150 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
2a160 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a  inter if N is.**
2a170 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
2a180 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69  ual to zero or i
2a190 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
2a1a0 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ate error occurs
2a1b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d  ..**.** ^(The am
2a1c0 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c  ount of space al
2a1d0 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
2a1e0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2a1f0 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20  text(C,N) is.** 
2a200 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68  determined by th
2a210 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  e N parameter on
2a220 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75   first successfu
2a230 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e  l call.  Changin
2a240 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  g the.** value o
2a250 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e  f N in subsequen
2a260 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
2a270 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2a280 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20  ext() within.** 
2a290 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
2a2a0 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
2a2b0 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65  ance will not re
2a2c0 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a  size the memory.
2a2d0 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e  ** allocation.)^
2a2e0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61  .**.** ^SQLite a
2a2f0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
2a300 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
2a310 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73  located by .** s
2a320 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2a330 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20  _context() when 
2a340 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75  the aggregate qu
2a350 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a  ery concludes..*
2a360 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
2a370 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65  arameter must be
2a380 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
2a390 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
2a3a0 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f  xt | SQL functio
2a3b0 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20  n context] that 
2a3c0 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
2a3d0 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
2a3e0 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c   xStep or xFinal
2a3f0 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
2a400 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  e that implement
2a410 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  s the aggregate.
2a420 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ** function..**.
2a430 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
2a440 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
2a450 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
2a460 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
2a470 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51  the aggregate SQ
2a480 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
2a490 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
2a4a0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2a4b0 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65  e_context(sqlite
2a4c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
2a4d0 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nBytes);../*.** 
2a4e0 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44  CAPI3REF: User D
2a4f0 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ata For Function
2a500 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
2a510 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
2a520 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2a530 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
2a540 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
2a550 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61   was the pUserDa
2a560 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  ta parameter (th
2a570 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29  e 5th parameter)
2a580 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
2a590 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2a5a0 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
2a5b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2a5c0 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
2a5d0 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
2a5e0 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
2a5f0 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
2a600 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
2a610 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
2a620 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
2a630 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
2a640 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
2a650 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c  hich.** the appl
2a660 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2a670 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
2a680 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
2a690 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2a6a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2a6b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2a6c0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2a6d0 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
2a6e0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
2a6f0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2a700 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74  _db_handle() int
2a710 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2a720 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
2a730 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
2a740 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2a750 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61  ion] (the 1st pa
2a760 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
2a770 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2a780 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
2a790 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
2a7a0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2a7b0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
2a7c0 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
2a7d0 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
2a7e0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
2a7f0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a  ed function..*/.
2a800 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33  sqlite3 *sqlite3
2a810 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
2a820 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
2a830 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
2a840 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
2a850 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a  Auxiliary Data.*
2a860 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
2a870 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  ng two functions
2a880 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20   may be used by 
2a890 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
2a8a0 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
2a8b0 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69  iate metadata wi
2a8c0 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75  th argument valu
2a8d0 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20  es. If the same 
2a8e0 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20  value is passed 
2a8f0 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69  to.** multiple i
2a900 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
2a910 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
2a920 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79  ion during query
2a930 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65   execution, unde
2a940 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d  r.** some circum
2a950 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f  stances the asso
2a960 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20  ciated metadata 
2a970 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
2a980 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65  . This may.** be
2a990 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70   used, for examp
2a9a0 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67  le, to add a reg
2a9b0 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20  ular-expression 
2a9c0 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a  matching scalar.
2a9d0 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
2a9e0 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
2a9f0 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
2aa00 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73   expression is s
2aa10 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61  tored as.** meta
2aa20 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
2aa30 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c  with the SQL val
2aa40 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
2aa50 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
2aa60 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20  ion.** pattern. 
2aa70 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   The compiled re
2aa80 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
2aa90 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
2aaa0 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
2aab0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
2aac0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73   same function s
2aad0 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69  o that the origi
2aae0 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69  nal pattern stri
2aaf0 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e  ng.** does not n
2ab00 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70  eed to be recomp
2ab10 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76  iled on each inv
2ab20 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ocation..**.** ^
2ab30 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
2ab40 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
2ab50 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2ab60 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74  inter to the met
2ab70 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  adata.** associa
2ab80 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
2ab90 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
2aba0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
2abb0 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a  he Nth argument.
2abc0 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  ** value to the 
2abd0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2abe0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49  ned function. ^I
2abf0 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61  f no metadata ha
2ac00 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62  s been ever.** b
2ac10 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20  een set for the 
2ac20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  Nth argument of 
2ac30 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72  the function, or
2ac40 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f   if the correspo
2ac50 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  nding.** functio
2ac60 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  n parameter has 
2ac70 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68  changed since th
2ac80 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20  e meta-data was 
2ac90 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c  set,.** then sql
2aca0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2acb0 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  () returns a NUL
2acc0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
2acd0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65   ^The sqlite3_se
2ace0 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
2acf0 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65 20  rface saves the 
2ad00 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e  metadata.** poin
2ad10 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 72  ted to by its 3r
2ad20 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
2ad30 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20  he metadata for 
2ad40 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75  the N-th.** argu
2ad50 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c  ment of the appl
2ad60 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2ad70 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65  function.  Subse
2ad80 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
2ad90 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  o sqlite3_get_au
2ada0 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 65  xdata() might re
2adb0 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20  turn this data, 
2adc0 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74  if it has.** not
2add0 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e   been destroyed.
2ade0 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f  .** ^If it is no
2adf0 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77  t NULL, SQLite w
2ae00 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  ill invoke the d
2ae10 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e  estructor.** fun
2ae20 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74  ction given by t
2ae30 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
2ae40 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
2ae50 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20  auxdata() on.** 
2ae60 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68 65  the metadata whe
2ae70 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
2ae80 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  ing function par
2ae90 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a  ameter changes.*
2aea0 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51  * or when the SQ
2aeb0 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
2aec0 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72  letes, whichever
2aed0 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a   comes first..**
2aee0 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72  .** SQLite is fr
2aef0 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64  ee to call the d
2af00 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72  estructor and dr
2af10 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61  op metadata on a
2af20 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  ny.** parameter 
2af30 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20  of any function 
2af40 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54  at any time.  ^T
2af50 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65  he only guarante
2af60 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  e is that.** the
2af70 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c   destructor will
2af80 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72   be called befor
2af90 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  e the metadata i
2afa0 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a  s dropped..**.**
2afb0 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20   ^(In practice, 
2afc0 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73  metadata is pres
2afd0 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75  erved between fu
2afe0 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72  nction calls for
2aff0 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20  .** expressions 
2b000 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e  that are constan
2b010 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  t at compile tim
2b020 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73  e. This includes
2b030 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75   literal.** valu
2b040 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65  es and [paramete
2b050 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs].)^.**.** The
2b060 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
2b070 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
2b080 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
2b090 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
2b0a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
2b0b0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
2b0c0 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   *sqlite3_get_au
2b0d0 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
2b0e0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  ntext*, int N);.
2b0f0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74  void sqlite3_set
2b100 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
2b110 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
2b120 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a  , void*, void (*
2b130 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a  )(void*));.../*.
2b140 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
2b150 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20  stants Defining 
2b160 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74  Special Destruct
2b170 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a  or Behavior.**.*
2b180 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63  * These are spec
2b190 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74  ial values for t
2b1a0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68  he destructor th
2b1b0 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20  at is passed in 
2b1c0 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  as the.** final 
2b1d0 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74  argument to rout
2b1e0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
2b1f0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
2b200 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74  ].  ^If the dest
2b210 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65  ructor.** argume
2b220 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41  nt is SQLITE_STA
2b230 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  TIC, it means th
2b240 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70  at the content p
2b250 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61  ointer is consta
2b260 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e  nt.** and will n
2b270 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74  ever change.  It
2b280 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
2b290 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20  o be destroyed. 
2b2a0 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f   ^The.** SQLITE_
2b2b0 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20  TRANSIENT value 
2b2c0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
2b2d0 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65  ontent will like
2b2e0 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ly change in.** 
2b2f0 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20  the near future 
2b300 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20  and that SQLite 
2b310 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20  should make its 
2b320 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
2b330 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
2b340 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  nt before return
2b350 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ing..**.** The t
2b360 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73  ypedef is necess
2b370 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  ary to work arou
2b380 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63  nd problems in c
2b390 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f  ertain.** C++ co
2b3a0 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69  mpilers.  See ti
2b3b0 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74  cket #2191..*/.t
2b3c0 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
2b3d0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
2b3e0 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23  _type)(void*);.#
2b3f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
2b400 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69  ATIC      ((sqli
2b410 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
2b420 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53  ype)0).#define S
2b430 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
2b440 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
2b450 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a  ructor_type)-1).
2b460 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b470 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73   Setting The Res
2b480 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75  ult Of An SQL Fu
2b490 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65  nction.**.** The
2b4a0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2b4b0 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e  used by the xFun
2b4c0 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  c or xFinal call
2b4d0 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d  backs that.** im
2b4e0 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63  plement SQL func
2b4f0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
2b500 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73  ates.  See.** [s
2b510 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2b520 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
2b530 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2b540 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66  nction16()].** f
2b550 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
2b560 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
2b570 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
2b580 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20   work very much 
2b590 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65  like the [parame
2b5a0 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d  ter binding] fam
2b5b0 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69  ily of.** functi
2b5c0 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64  ons used to bind
2b5d0 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
2b5e0 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72  parameters in pr
2b5f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b600 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74  s..** Refer to t
2b610 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  he [SQL paramete
2b620 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  r] documentation
2b630 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2b640 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
2b650 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2b660 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e  result_blob() in
2b670 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
2b680 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
2b690 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
2b6a0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2b6b0 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77  to be the BLOB w
2b6c0 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20  hose content is 
2b6d0 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79  pointed.** to by
2b6e0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
2b6f0 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20  meter and which 
2b700 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20  is N bytes long 
2b710 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
2b720 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
2b730 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
2b740 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
2b750 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  oblob() interfac
2b760 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c  es set the resul
2b770 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
2b780 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2b790 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
2b7a0 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67   BLOB containing
2b7b0 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74   all zero.** byt
2b7c0 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69  es and N bytes i
2b7d0 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20  n size, where N 
2b7e0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
2b7f0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2b800 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
2b810 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
2b820 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
2b830 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
2b840 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
2b850 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2b860 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
2b870 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
2b880 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a  alue specified.*
2b890 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67  * by its 2nd arg
2b8a0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
2b8b0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2b8c0 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
2b8d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2b8e0 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a  r16() functions.
2b8f0 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70  ** cause the imp
2b900 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e  lemented SQL fun
2b910 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61  ction to throw a
2b920 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20  n exception..** 
2b930 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
2b940 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20   string pointed 
2b950 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64  to by the.** 2nd
2b960 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
2b970 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2b980 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  or() or sqlite3_
2b990 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
2b9a0 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20  .** as the text 
2b9b0 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  of an error mess
2b9c0 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e  age.  ^SQLite in
2b9d0 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
2b9e0 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74  or.** message st
2b9f0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
2ba00 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
2ba10 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69   as UTF-8. ^SQLi
2ba20 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73  te.** interprets
2ba30 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d   the string from
2ba40 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2ba50 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46  error16() as UTF
2ba60 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a  -16 in native.**
2ba70 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49   byte order.  ^I
2ba80 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
2ba90 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2baa0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
2bab0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
2bac0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
2bad0 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  s negative then 
2bae0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20  SQLite takes as 
2baf0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
2bb00 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70  sage all text up
2bb10 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
2bb20 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
2bb30 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68  r..** ^If the th
2bb40 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
2bb50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2bb60 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71  error() or.** sq
2bb70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2bb80 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65  or16() is non-ne
2bb90 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
2bba0 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61  te takes that ma
2bbb0 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74  ny.** bytes (not
2bbc0 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f   characters) fro
2bbd0 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
2bbe0 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72  ter as the error
2bbf0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68   message..** ^Th
2bc00 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2bc10 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
2bc20 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2bc30 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  r16().** routine
2bc40 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65  s make a private
2bc50 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72   copy of the err
2bc60 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
2bc70 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72  before.** they r
2bc80 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74  eturn.  Hence, t
2bc90 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
2bca0 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61  ion can dealloca
2bcb0 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20  te or.** modify 
2bcc0 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74  the text after t
2bcd0 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f  hey return witho
2bce0 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65  ut harm..** ^The
2bcf0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2bd00 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e  error_code() fun
2bd10 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68  ction changes th
2bd20 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  e error code.** 
2bd30 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69  returned by SQLi
2bd40 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f  te as a result o
2bd50 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20  f an error in a 
2bd60 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64  function.  ^By d
2bd70 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65  efault,.** the e
2bd80 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c  rror code is SQL
2bd90 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73  ITE_ERROR.  ^A s
2bda0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
2bdb0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
2bdc0 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
2bdd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2bde0 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
2bdf0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
2be00 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
2be10 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2be20 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28  3_result_toobig(
2be30 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
2be40 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
2be50 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69  ow an error.** i
2be60 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
2be70 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
2be80 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72  is too long to r
2be90 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  epresent..**.** 
2bea0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2beb0 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ult_nomem() inte
2bec0 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
2bed0 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
2bee0 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
2bef0 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72  ing that a memor
2bf00 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
2bf10 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
2bf20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
2bf30 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  nt() interface s
2bf40 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
2bf50 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
2bf60 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2bf70 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2bf80 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67  e the 32-bit sig
2bf90 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
2bfa0 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
2bfb0 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
2bfc0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2bfd0 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69  result_int64() i
2bfe0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2bff0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
2c000 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
2c010 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2c020 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
2c030 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
2c040 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
2c050 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
2c060 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
2c070 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2c080 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72  ult_null() inter
2c090 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
2c0a0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
2c0b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2c0c0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2c0d0 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  n to be NULL..**
2c0e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2c0f0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20  _result_text(), 
2c100 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2c110 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69  ext16(),.** sqli
2c120 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2c130 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  6le(), and sqlit
2c140 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2c150 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  be() interfaces.
2c160 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72  ** set the retur
2c170 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61  n value of the a
2c180 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2c190 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2c1a0 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69  e.** a text stri
2c1b0 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72  ng which is repr
2c1c0 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38  esented as UTF-8
2c1d0 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  , UTF-16 native 
2c1e0 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55  byte order,.** U
2c1f0 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64  TF-16 little end
2c200 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
2c210 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig endian, respe
2c220 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c  ctively..** ^SQL
2c230 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65  ite takes the te
2c240 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74  xt result from t
2c250 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66  he application f
2c260 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70  rom.** the 2nd p
2c270 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
2c280 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2c290 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ext* interfaces.
2c2a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
2c2b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2c2c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2c2d0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
2c2e0 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
2c2f0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
2c300 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
2c310 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
2c320 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68  meter.** through
2c330 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
2c340 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
2c350 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
2c360 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
2c370 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2c380 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
2c390 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
2c3a0 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65  hen as many byte
2c3b0 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
2c3c0 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a  s) of the text.*
2c3d0 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
2c3e0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2c3f0 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74  r are taken as t
2c400 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2c410 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69  efined.** functi
2c420 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  on result..** ^I
2c430 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
2c440 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
2c450 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2c460 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
2c470 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2c480 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55  blob is a non-NU
2c490 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
2c4a0 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68   SQLite calls th
2c4b0 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61  at.** function a
2c4c0 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  s the destructor
2c4d0 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20   on the text or 
2c4e0 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e  BLOB result when
2c4f0 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73   it has.** finis
2c500 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
2c510 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
2c520 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
2c530 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
2c540 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
2c550 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20  rfaces or to.** 
2c560 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2c570 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
2c580 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
2c590 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20  TE_STATIC, then 
2c5a0 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65  SQLite.** assume
2c5b0 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20  s that the text 
2c5c0 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69  or BLOB result i
2c5d0 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70  s in constant sp
2c5e0 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
2c5f0 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e  .** copy the con
2c600 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61  tent of the para
2c610 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61  meter nor call a
2c620 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
2c630 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68  he content.** wh
2c640 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  en it has finish
2c650 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
2c660 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  sult..** ^If the
2c670 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
2c680 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
2c690 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
2c6a0 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
2c6b0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
2c6c0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
2c6d0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54  onstant SQLITE_T
2c6e0 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e  RANSIENT.** then
2c6f0 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20   SQLite makes a 
2c700 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75  copy of the resu
2c710 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62  lt into space ob
2c720 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66  tained from.** f
2c730 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
2c740 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74  loc()] before it
2c750 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
2c760 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2c770 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
2c780 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
2c790 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
2c7a0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2c7b0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2c7c0 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a  be a copy the.**
2c7d0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2c7e0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2c7f0 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79  ect specified by
2c800 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2c810 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  er.  ^The.** sql
2c820 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2c830 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61  e() interface ma
2c840 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
2c850 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2c860 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65  ].** so that the
2c870 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
2c880 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68   specified in th
2c890 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
2c8a0 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20  change or.** be 
2c8b0 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65  deallocated afte
2c8c0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
2c8d0 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73  _value() returns
2c8e0 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
2c8f0 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20  * ^A [protected 
2c900 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2c910 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73  bject may always
2c920 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61   be used where a
2c930 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
2c940 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2c950 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69   object is requi
2c960 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a  red, so either.*
2c970 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74  * kind of [sqlit
2c980 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2c990 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74   can be used wit
2c9a0 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  h this interface
2c9b0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65  ..**.** If these
2c9c0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
2c9d0 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e  lled from within
2c9e0 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74   the different t
2c9f0 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68  hread.** than th
2ca00 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67  e one containing
2ca10 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2ca20 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2ca30 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a  n that received.
2ca40 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
2ca50 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72  context] pointer
2ca60 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
2ca70 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
2ca80 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2ca90 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ult_blob(sqlite3
2caa0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2cab0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
2cac0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
2cad0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2cae0 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
2caf0 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
2cb00 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  e);.void sqlite3
2cb10 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
2cb20 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2cb30 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
2cb40 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2cb50 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
2cb60 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2cb70 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2cb80 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
2cb90 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
2cba0 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e  obig(sqlite3_con
2cbb0 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
2cbc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2cbd0 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f  r_nomem(sqlite3_
2cbe0 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
2cbf0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2cc00 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65  rror_code(sqlite
2cc10 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
2cc20 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2cc30 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65  esult_int(sqlite
2cc40 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
2cc50 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2cc60 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69  esult_int64(sqli
2cc70 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
2cc80 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f  lite3_int64);.vo
2cc90 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2cca0 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63  t_null(sqlite3_c
2ccb0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
2ccc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2ccd0 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
2cce0 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
2ccf0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
2cd00 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
2cd10 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2cd20 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
2cd30 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
2cd40 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
2cd50 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
2cd60 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2cd70 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16le(sqlite3_con
2cd80 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
2cd90 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
2cda0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
2cdb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2cdc0 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
2cdd0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
2cde0 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
2cdf0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
2ce00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2ce10 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lue(sqlite3_cont
2ce20 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61  ext*, sqlite3_va
2ce30 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  lue*);.void sqli
2ce40 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
2ce50 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
2ce60 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f  ext*, int n);../
2ce70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2ce80 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74  efine New Collat
2ce90 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a  ing Sequences.**
2cea0 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
2ceb0 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65  ions add, remove
2cec0 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63  , or modify a [c
2ced0 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69  ollation] associ
2cee0 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ated.** with the
2cef0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2cf00 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
2cf10 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
2cf20 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
2cf30 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
2cf40 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54  ollation is a UT
2cf50 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f  F-8 string.** fo
2cf60 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
2cf70 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64  _collation() and
2cf80 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2cf90 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a  collation_v2().*
2cfa0 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73  * and a UTF-16 s
2cfb0 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
2cfc0 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73  byte order for s
2cfd0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2cfe0 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20  llation16()..** 
2cff0 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73  ^Collation names
2d000 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71   that compare eq
2d010 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  ual according to
2d020 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63   [sqlite3_strnic
2d030 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e  mp()] are.** con
2d040 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 74 68  sidered to be th
2d050 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a  e same name..**.
2d060 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20 61  ** ^(The third a
2d070 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65  rgument (eTextRe
2d080 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f  p) must be one o
2d090 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a  f the constants:
2d0a0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
2d0b0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a   [SQLITE_UTF8],.
2d0c0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
2d0d0 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69  UTF16LE],.** <li
2d0e0 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  > [SQLITE_UTF16B
2d0f0 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
2d100 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a  ITE_UTF16], or.*
2d110 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
2d120 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a  TF16_ALIGNED]..*
2d130 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68  * </ul>)^.** ^Th
2d140 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d  e eTextRep argum
2d150 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ent determines t
2d160 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73  he encoding of s
2d170 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a  trings passed.**
2d180 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
2d190 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
2d1a0 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a  ack, xCallback..
2d1b0 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
2d1c0 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49  UTF16] and [SQLI
2d1d0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
2d1e0 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65  ] values for eTe
2d1f0 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73  xtRep.** force s
2d200 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46  trings to be UTF
2d210 31 36 20 77 69 74 68 20 6e 61 74 69 76 65 20 62  16 with native b
2d220 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54  yte order..** ^T
2d230 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  he [SQLITE_UTF16
2d240 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20  _ALIGNED] value 
2d250 66 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f 72  for eTextRep for
2d260 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62  ces strings to b
2d270 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76  egin.** on an ev
2d280 65 6e 20 62 79 74 65 20 61 64 64 72 65 73 73 2e  en byte address.
2d290 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
2d2a0 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72  th argument, pAr
2d2b0 67 2c 20 69 73 20 61 20 61 70 70 6c 69 63 61 74  g, is a applicat
2d2c0 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
2d2d0 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 0a   that is passed.
2d2e0 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ** through as th
2d2f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2d300 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
2d310 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
2d320 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ack..**.** ^The 
2d330 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  fifth argument, 
2d340 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20  xCallback, is a 
2d350 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63  pointer to the c
2d360 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2d370 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20  n..** ^Multiple 
2d380 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
2d390 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69 73  ons can be regis
2d3a0 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
2d3b0 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a  same name but.**
2d3c0 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
2d3d0 65 54 65 78 74 52 65 70 20 70 61 72 61 6d 65 74  eTextRep paramet
2d3e0 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77  ers and SQLite w
2d3f0 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76 65  ill use whicheve
2d400 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  r.** function re
2d410 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74  quires the least
2d420 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
2d430 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a  transformation..
2d440 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c  ** ^If the xCall
2d450 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73  back argument is
2d460 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63   NULL then the c
2d470 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2d480 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e  n is.** deleted.
2d490 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c    ^When all coll
2d4a0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
2d4b0 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20  having the same 
2d4c0 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64  name are deleted
2d4d0 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74  ,.** that collat
2d4e0 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  ion is no longer
2d4f0 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e   usable..**.** ^
2d500 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
2d510 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20  nction callback 
2d520 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
2d530 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41  a copy of the pA
2d540 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  rg .** applicati
2d550 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  on data pointer 
2d560 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74 72  and with two str
2d570 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f  ings in the enco
2d580 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a  ding specified.*
2d590 2a 20 62 79 20 74 68 65 20 65 54 65 78 74 52 65  * by the eTextRe
2d5a0 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65  p argument.  The
2d5b0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
2d5c0 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20  ion must return 
2d5d0 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68  an.** integer th
2d5e0 61 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  at is negative, 
2d5f0 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76  zero, or positiv
2d600 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73  e.** if the firs
2d610 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73  t string is less
2d620 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c   than, equal to,
2d630 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
2d640 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20   the second,.** 
2d650 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41  respectively.  A
2d660 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
2d670 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 20 72  ion must alway r
2d680 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61  eturn the same a
2d690 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74  nswer.** given t
2d6a0 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20  he same inputs. 
2d6b0 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
2d6c0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
2d6d0 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74 65 72  ons are register
2d6e0 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d  ed.** to the sam
2d6f0 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65  e collation name
2d700 20 28 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e   (using differen
2d710 74 20 65 54 65 78 74 52 65 70 20 76 61 6c 75 65  t eTextRep value
2d720 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d  s) then all.** m
2d730 75 73 74 20 67 69 76 65 20 61 6e 20 65 71 75 69  ust give an equi
2d740 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68  valent answer wh
2d750 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  en invoked with 
2d760 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e  equivalent strin
2d770 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61  gs..** The colla
2d780 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
2d790 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c  st obey the foll
2d7a0 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73  owing properties
2d7b0 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69   for all.** stri
2d7c0 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a  ngs A, B, and C:
2d7d0 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
2d7e0 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e  li> If A==B then
2d7f0 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49   B==A..** <li> I
2d800 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20  f A==B and B==C 
2d810 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c  then A==C..** <l
2d820 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45  i> If A&lt;B THE
2d830 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69  N B&gt;A..** <li
2d840 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20  > If A&lt;B and 
2d850 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74  B&lt;C then A&lt
2d860 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  ;C..** </ol>.**.
2d870 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e  ** If a collatin
2d880 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73  g function fails
2d890 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76   any of the abov
2d8a0 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e  e constraints an
2d8b0 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74  d that.** collat
2d8c0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
2d8d0 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 20   registered and 
2d8e0 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62  used, then the b
2d8f0 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
2d900 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  e.** is undefine
2d910 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
2d920 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2d930 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b  lation_v2() work
2d940 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63  s like sqlite3_c
2d950 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2d960 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64  ).** with the ad
2d970 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20  dition that the 
2d980 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63  xDestroy callbac
2d990 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  k is invoked on 
2d9a0 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65  pArg when.** the
2d9b0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
2d9c0 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a  ion is deleted..
2d9d0 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75  ** ^Collating fu
2d9e0 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65  nctions are dele
2d9f0 74 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72  ted when they ar
2da00 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
2da10 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  later.** calls t
2da20 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  o the collation 
2da30 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  creation functio
2da40 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a  ns or when the.*
2da50 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
2da60 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65  ection] is close
2da70 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
2da80 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _close()]..**.**
2da90 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20 63   ^The xDestroy c
2daa0 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f  allback is <u>no
2dab0 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20  t</u> called if 
2dac0 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  the .** sqlite3_
2dad0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2dae0 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66  _v2() function f
2daf0 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69  ails.  Applicati
2db00 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a  ons that invoke.
2db10 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
2db20 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
2db30 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
2db40 20 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65   xDestroy argume
2db50 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68  nt should .** ch
2db60 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
2db70 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20  ode and dispose 
2db80 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
2db90 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a  on data pointer.
2dba0 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61  ** themselves ra
2dbb0 74 68 65 72 20 74 68 61 6e 20 65 78 70 65 63 74  ther than expect
2dbc0 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65  ing SQLite to de
2dbd0 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20 74  al with it for t
2dbe0 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  hem..** This is 
2dbf0 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65  different from e
2dc00 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74  very other SQLit
2dc10 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  e interface.  Th
2dc20 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20  e inconsistency 
2dc30 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61  .** is unfortuna
2dc40 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65  te but cannot be
2dc50 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74   changed without
2dc60 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61   breaking backwa
2dc70 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  rds .** compatib
2dc80 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ility..**.** See
2dc90 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33   also:  [sqlite3
2dca0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2dcb0 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
2dcc0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2dcd0 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ed16()]..*/.int 
2dce0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2dcf0 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69  ollation(.  sqli
2dd00 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
2dd10 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
2dd20 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
2dd30 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
2dd40 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
2dd50 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
2dd60 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
2dd70 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  d*).);.int sqlit
2dd80 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2dd90 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
2dda0 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
2ddb0 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
2ddc0 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
2ddd0 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
2dde0 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
2ddf0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
2de00 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
2de10 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
2de20 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69  roy)(void*).);.i
2de30 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2de40 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20  e_collation16(. 
2de50 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
2de60 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c  nst void *zName,
2de70 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2de80 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
2de90 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
2dea0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
2deb0 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
2dec0 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
2ded0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c  * CAPI3REF: Coll
2dee0 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c  ation Needed Cal
2def0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f  lbacks.**.** ^To
2df00 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f   avoid having to
2df10 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f   register all co
2df20 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2df30 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62  s before a datab
2df40 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ase.** can be us
2df50 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c  ed, a single cal
2df60 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
2df70 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
2df80 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61   with the.** [da
2df90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2dfa0 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  n] to be invoked
2dfb0 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64   whenever an und
2dfc0 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
2dfd0 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20  .** sequence is 
2dfe0 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
2dff0 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
2e000 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75   is registered u
2e010 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
2e020 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2e030 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e  d() API,.** then
2e040 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68   it is passed th
2e050 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66  e names of undef
2e060 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ined collation s
2e070 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69  equences as stri
2e080 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69  ngs.** encoded i
2e090 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c  n UTF-8. ^If sql
2e0a0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2e0b0 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
2e0c0 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20  d,.** the names 
2e0d0 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
2e0e0 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
2e0f0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2e100 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  r..** ^A call to
2e110 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e   either function
2e120 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 65 78   replaces the ex
2e130 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e  isting collation
2e140 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b  -needed callback
2e150 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74  ..**.** ^(When t
2e160 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
2e170 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73  nvoked, the firs
2e180 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  t argument passe
2e190 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  d is a copy.** o
2e1a0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
2e1b0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
2e1c0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2e1d0 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  d() or.** sqlite
2e1e0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2e1f0 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63  ed16().  The sec
2e200 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
2e210 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
2e220 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
2e230 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
2e240 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
2e250 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
2e260 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72  _UTF16BE],.** or
2e270 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
2e280 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
2e290 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65  e most desirable
2e2a0 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c   form of the col
2e2b0 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
2e2c0 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ce function requ
2e2d0 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74  ired.  The fourt
2e2e0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  h parameter is t
2e2f0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
2e300 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61  * required colla
2e310 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e  tion sequence.)^
2e320 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
2e330 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
2e340 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65  uld register the
2e350 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69   desired collati
2e360 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
2e370 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2e380 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ation()], [sqlit
2e390 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2e3a0 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
2e3b0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2e3c0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e  collation_v2()].
2e3d0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2e3e0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2e3f0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2e400 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28   void*, .  void(
2e410 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
2e420 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
2e430 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69  onst char*).);.i
2e440 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
2e450 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20  tion_needed16(. 
2e460 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
2e470 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76  id*,.  void(*)(v
2e480 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
2e490 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
2e4a0 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64   void*).);..#ifd
2e4b0 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f  ef SQLITE_HAS_CO
2e4c0 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  DEC./*.** Specif
2e4d0 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e  y the key for an
2e4e0 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62   encrypted datab
2e4f0 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ase.  This routi
2e500 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  ne should be.** 
2e510 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74  called right aft
2e520 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  er sqlite3_open(
2e530 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  )..**.** The cod
2e540 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
2e550 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
2e560 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
2e570 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
2e580 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
2e590 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28  int sqlite3_key(
2e5a0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2e5b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e5c0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
2e5d0 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
2e5e0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
2e5f0 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
2e600 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
2e610 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74  ../*.** Change t
2e620 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65  he key on an ope
2e630 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20  n database.  If 
2e640 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61  the current data
2e650 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65  base is not.** e
2e660 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72  ncrypted, this r
2e670 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72  outine will encr
2e680 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77  ypt it.  If pNew
2e690 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20  ==0 or nNew==0, 
2e6a0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
2e6b0 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a  is decrypted..**
2e6c0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
2e6d0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
2e6e0 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
2e6f0 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
2e700 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
2e710 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
2e720 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20  qlite3_rekey(.  
2e730 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2e740 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
2e750 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
2e760 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
2e770 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
2e780 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
2e790 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
2e7a0 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  ;../*.** Specify
2e7b0 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20   the activation 
2e7c0 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20 64 61  key for a SEE da
2e7d0 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20  tabase.  Unless 
2e7e0 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e  .** activated, n
2e7f0 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20 72  one of the SEE r
2e800 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72  outines will wor
2e810 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  k..*/.void sqlit
2e820 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28  e3_activate_see(
2e830 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2e840 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20  PassPhrase      
2e850 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20    /* Activation 
2e860 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e  phrase */.);.#en
2e870 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49  dif..#ifdef SQLI
2e880 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a  TE_ENABLE_CEROD.
2e890 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
2e8a0 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79  e activation key
2e8b0 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74   for a CEROD dat
2e8c0 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a  abase.  Unless .
2e8d0 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f  ** activated, no
2e8e0 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20  ne of the CEROD 
2e8f0 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f  routines will wo
2e900 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  rk..*/.void sqli
2e910 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72  te3_activate_cer
2e920 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  od(.  const char
2e930 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20   *zPassPhrase   
2e940 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69       /* Activati
2e950 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a  on phrase */.);.
2e960 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
2e970 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20  PI3REF: Suspend 
2e980 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20  Execution For A 
2e990 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a  Short Time.**.**
2e9a0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65   The sqlite3_sle
2e9b0 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61  ep() function ca
2e9c0 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74  uses the current
2e9d0 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65   thread to suspe
2e9e0 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20  nd execution.** 
2e9f0 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e  for at least a n
2ea00 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
2ea10 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20  conds specified 
2ea20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  in its parameter
2ea30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f  ..**.** If the o
2ea40 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
2ea50 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  does not support
2ea60 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20   sleep requests 
2ea70 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63  with.** millisec
2ea80 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74  ond time resolut
2ea90 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69  ion, then the ti
2eaa0 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64  me will be round
2eab0 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20  ed up to.** the 
2eac0 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20  nearest second. 
2ead0 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  The number of mi
2eae0 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
2eaf0 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20  eep actually.** 
2eb00 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74  requested from t
2eb10 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
2eb20 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  tem is returned.
2eb30 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69  .**.** ^SQLite i
2eb40 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69  mplements this i
2eb50 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c  nterface by call
2eb60 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29  ing the xSleep()
2eb70 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  .** method of th
2eb80 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
2eb90 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20  e3_vfs] object. 
2eba0 20 49 66 20 74 68 65 20 78 53 6c 65 65 70 28 29   If the xSleep()
2ebb0 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
2ebc0 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73  e default VFS is
2ebd0 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64   not implemented
2ebe0 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e   correctly, or n
2ebf0 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  ot implemented a
2ec00 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74  t.** all, then t
2ec10 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
2ec20 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 6d  qlite3_sleep() m
2ec30 61 79 20 64 65 76 69 61 74 65 20 66 72 6f 6d 20  ay deviate from 
2ec40 74 68 65 20 64 65 73 63 72 69 70 74 69 6f 6e 0a  the description.
2ec50 2a 2a 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ** in the previo
2ec60 75 73 20 70 61 72 61 67 72 61 70 68 73 2e 0a 2a  us paragraphs..*
2ec70 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c  /.int sqlite3_sl
2ec80 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  eep(int);../*.**
2ec90 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
2eca0 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f  Of The Folder Ho
2ecb0 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20  lding Temporary 
2ecc0 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  Files.**.** ^(If
2ecd0 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72   this global var
2ece0 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f  iable is made to
2ecf0 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69   point to a stri
2ed00 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74  ng which is.** t
2ed10 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c  he name of a fol
2ed20 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65  der (a.k.a. dire
2ed30 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c  ctory), then all
2ed40 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
2ed50 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53  .** created by S
2ed60 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67  QLite when using
2ed70 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c   a built-in [sql
2ed80 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a  ite3_vfs | VFS].
2ed90 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65  ** will be place
2eda0 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74  d in that direct
2edb0 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73  ory.)^  ^If this
2edc0 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20   variable.** is 
2edd0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
2ede0 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66  then SQLite perf
2edf0 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f  orms a search fo
2ee00 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  r an appropriate
2ee10 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
2ee20 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  le directory..**
2ee30 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
2ee40 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
2ee50 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
2ee60 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20  le in more than 
2ee70 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74  one.** thread at
2ee80 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20   a time.  It is 
2ee90 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
2eea0 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
2eeb0 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61  variable.** if a
2eec0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2eed0 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
2eee0 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65  used at the same
2eef0 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72   time in a separ
2ef00 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a  ate.** thread..*
2ef10 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64  * It is intended
2ef20 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
2ef30 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a  ble be set once.
2ef40 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72  ** as part of pr
2ef50 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
2ef60 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20  tion and before 
2ef70 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
2ef80 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  face.** routines
2ef90 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
2efa0 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  d and that this 
2efb0 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20  variable remain 
2efc0 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65  unchanged.** the
2efd0 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  reafter..**.** ^
2efe0 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  The [temp_store_
2eff0 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
2f000 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69  ] may modify thi
2f010 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63  s variable and c
2f020 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f  ause.** it to po
2f030 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
2f040 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
2f050 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e  ite3_malloc].  ^
2f060 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20  Furthermore,.** 
2f070 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  the [temp_store_
2f080 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
2f090 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73  ] always assumes
2f0a0 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67   that any string
2f0b0 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61  .** that this va
2f0c0 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f  riable points to
2f0d0 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f   is held in memo
2f0e0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
2f0f0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
2f100 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72  lloc] and the pr
2f110 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74  agma may attempt
2f120 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65   to free that me
2f130 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  mory.** using [s
2f140 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a  qlite3_free]..**
2f150 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20   Hence, if this 
2f160 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69  variable is modi
2f170 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65  fied directly, e
2f180 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20  ither it should 
2f190 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20  be.** made NULL 
2f1a0 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  or made to point
2f1b0 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   to memory obtai
2f1c0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2f1d0 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20  3_malloc].** or 
2f1e0 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20  else the use of 
2f1f0 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  the [temp_store_
2f200 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
2f210 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69  ] should be avoi
2f220 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ded..*/.SQLITE_E
2f230 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69  XTERN char *sqli
2f240 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
2f250 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ry;../*.** CAPI3
2f260 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75  REF: Test For Au
2f270 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a  to-Commit Mode.*
2f280 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74  * KEYWORDS: {aut
2f290 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a  ocommit mode}.**
2f2a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2f2b0 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
2f2c0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2f2d0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a  rns non-zero or.
2f2e0 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67  ** zero if the g
2f2f0 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f  iven database co
2f300 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69  nnection is or i
2f310 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d  s not in autocom
2f320 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73  mit mode,.** res
2f330 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74  pectively.  ^Aut
2f340 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
2f350 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  on by default..*
2f360 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  * ^Autocommit mo
2f370 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  de is disabled b
2f380 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74  y a [BEGIN] stat
2f390 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63  ement..** ^Autoc
2f3a0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65  ommit mode is re
2f3b0 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43  -enabled by a [C
2f3c0 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42  OMMIT] or [ROLLB
2f3d0 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63  ACK]..**.** If c
2f3e0 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20  ertain kinds of 
2f3f0 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20  errors occur on 
2f400 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  a statement with
2f410 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65  in a multi-state
2f420 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ment.** transact
2f430 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c  ion (errors incl
2f440 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55  uding [SQLITE_FU
2f450 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45  LL], [SQLITE_IOE
2f460 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  RR],.** [SQLITE_
2f470 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f  NOMEM], [SQLITE_
2f480 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  BUSY], and [SQLI
2f490 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74  TE_INTERRUPT]) t
2f4a0 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73  hen the.** trans
2f4b0 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  action might be 
2f4c0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
2f4d0 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20  matically.  The 
2f4e0 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66  only way to.** f
2f4f0 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20  ind out whether 
2f500 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
2f510 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2f520 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
2f530 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72   after.** an err
2f540 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69  or is to use thi
2f550 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  s function..**.*
2f560 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72  * If another thr
2f570 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20  ead changes the 
2f580 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75  autocommit statu
2f590 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  s of the databas
2f5a0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
2f5b0 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69  while this routi
2f5c0 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74  ne is running, t
2f5d0 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
2f5e0 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66  alue.** is undef
2f5f0 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
2f600 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
2f610 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  mit(sqlite3*);..
2f620 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2f630 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73  Find The Databas
2f640 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72  e Handle Of A Pr
2f650 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2f660 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f670 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e  te3_db_handle in
2f680 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2f690 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2f6a0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
2f6b0 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b  .** to which a [
2f6c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f6d0 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54  nt] belongs.  ^T
2f6e0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2f6f0 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75  nection].** retu
2f700 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2f710 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65  db_handle is the
2f720 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
2f730 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74  connection].** t
2f740 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73  hat was the firs
2f750 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  t argument.** to
2f760 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
2f770 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c  epare_v2()] call
2f780 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74   (or its variant
2f790 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64  s) that was used
2f7a0 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68   to.** create th
2f7b0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  e statement in t
2f7c0 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a  he first place..
2f7d0 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
2f7e0 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  te3_db_handle(sq
2f7f0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2f800 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
2f810 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65  ind the next pre
2f820 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
2f830 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
2f840 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2f850 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e  pointer to the n
2f860 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74  ext [prepared st
2f870 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a  atement] after.*
2f880 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74  * pStmt associat
2f890 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
2f8a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2f8b0 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53 74 6d  ] pDb.  ^If pStm
2f8c0 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65  t is NULL.** the
2f8d0 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  n this interface
2f8e0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2f8f0 65 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  er to the first 
2f900 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f910 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  nt.** associated
2f920 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61   with the databa
2f930 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44  se connection pD
2f940 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65 70 61  b.  ^If no prepa
2f950 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
2f960 20 73 61 74 69 73 66 69 65 73 20 74 68 65 20 63   satisfies the c
2f970 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69  onditions of thi
2f980 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65  s routine, it re
2f990 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  turns NULL..**.*
2f9a0 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20  * The [database 
2f9b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e  connection] poin
2f9c0 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20  ter D in a call 
2f9d0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e  to.** [sqlite3_n
2f9e0 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d  ext_stmt(D,S)] m
2f9f0 75 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20  ust refer to an 
2fa00 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a  open database.**
2fa10 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20   connection and 
2fa20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75  in particular mu
2fa30 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c  st not be a NULL
2fa40 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c   pointer..*/.sql
2fa50 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74  ite3_stmt *sqlit
2fa60 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c  e3_next_stmt(sql
2fa70 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74  ite3 *pDb, sqlit
2fa80 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2fa90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2faa0 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c  : Commit And Rol
2fab0 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69  lback Notificati
2fac0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
2fad0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2fae0 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e  commit_hook() in
2faf0 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
2fb00 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  s a callback.** 
2fb10 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
2fb20 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
2fb30 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
2fb40 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69   [COMMIT | commi
2fb50 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63  tted]..** ^Any c
2fb60 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
2fb70 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2fb80 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  o sqlite3_commit
2fb90 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74  _hook().** for t
2fba0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
2fbb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
2fbc0 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54  verridden..** ^T
2fbd0 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  he sqlite3_rollb
2fbe0 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  ack_hook() inter
2fbf0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
2fc00 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
2fc10 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
2fc20 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74  ked whenever a t
2fc30 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52  ransaction is [R
2fc40 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64  OLLBACK | rolled
2fc50 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20   back]..** ^Any 
2fc60 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
2fc70 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
2fc80 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  to sqlite3_rollb
2fc90 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f  ack_hook().** fo
2fca0 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
2fcb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
2fcc0 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
2fcd0 20 5e 54 68 65 20 70 41 72 67 20 61 72 67 75 6d   ^The pArg argum
2fce0 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68  ent is passed th
2fcf0 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c  rough to the cal
2fd00 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68  lback..** ^If th
2fd10 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20  e callback on a 
2fd20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63  commit hook func
2fd30 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e  tion returns non
2fd40 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74  -zero,.** then t
2fd50 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e  he commit is con
2fd60 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f  verted into a ro
2fd70 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54  llback..**.** ^T
2fd80 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  he sqlite3_commi
2fd90 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e  t_hook(D,C,P) an
2fda0 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  d sqlite3_rollba
2fdb0 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66  ck_hook(D,C,P) f
2fdc0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75  unctions.** retu
2fdd0 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e  rn the P argumen
2fde0 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69  t from the previ
2fdf0 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 20  ous call of the 
2fe00 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  same function.**
2fe10 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
2fe20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2fe30 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f  n] D, or NULL fo
2fe40 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63  r.** the first c
2fe50 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75 6e  all for each fun
2fe60 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a  ction on D..**.*
2fe70 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  * The callback i
2fe80 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
2fe90 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
2fea0 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
2feb0 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
2fec0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
2fed0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
2fee0 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61  callback.  Any a
2fef0 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64  ctions.** to mod
2ff00 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
2ff10 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
2ff20 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74   be deferred unt
2ff30 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20  il after the.** 
2ff40 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68  completion of th
2ff50 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
2ff60 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  )] call that tri
2ff70 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69  ggered the commi
2ff80 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  t.** or rollback
2ff90 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72   hook in the fir
2ffa0 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74  st place..** Not
2ffb0 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
2ffc0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
2ffd0 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
2ffe0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
2fff0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
30000 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
30010 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
30020 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
30030 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
30040 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61  * ^Registering a
30050 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64   NULL function d
30060 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c  isables the call
30070 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  back..**.** ^Whe
30080 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f  n the commit hoo
30090 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  k callback routi
300a0 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c  ne returns zero,
300b0 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a   the [COMMIT].**
300c0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c   operation is al
300d0 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75  lowed to continu
300e0 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66  e normally.  ^If
300f0 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b   the commit hook
30100 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  .** returns non-
30110 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b  zero, then the [
30120 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65  COMMIT] is conve
30130 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c  rted into a [ROL
30140 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20  LBACK]..** ^The 
30150 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73  rollback hook is
30160 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f   invoked on a ro
30170 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73 75  llback that resu
30180 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69  lts from a commi
30190 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e  t.** hook return
301a0 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75  ing non-zero, ju
301b0 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62  st as it would b
301c0 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72  e with any other
301d0 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   rollback..**.**
301e0 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73   ^For the purpos
301f0 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20  es of this API, 
30200 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
30210 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65   said to have be
30220 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63  en.** rolled bac
30230 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74  k if an explicit
30240 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74   "ROLLBACK" stat
30250 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65  ement is execute
30260 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f  d, or.** an erro
30270 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20  r or constraint 
30280 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63  causes an implic
30290 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f  it rollback to o
302a0 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f  ccur..** ^The ro
302b0 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20  llback callback 
302c0 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69  is not invoked i
302d0 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  f a transaction 
302e0 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  is.** automatica
302f0 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
30300 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61  because the data
30310 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
30320 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
30330 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
30340 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
30350 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ok()] interface.
30360 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
30370 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71  3_commit_hook(sq
30380 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
30390 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76  oid*), void*);.v
303a0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c  oid *sqlite3_rol
303b0 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74  lback_hook(sqlit
303c0 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  e3*, void(*)(voi
303d0 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  d *), void*);../
303e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
303f0 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66  ata Change Notif
30400 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
30410 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
30420 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
30430 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
30440 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
30450 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  k function.** wi
30460 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
30470 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65   connection] ide
30480 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ntified by the f
30490 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  irst argument.**
304a0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
304b0 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73  henever a row is
304c0 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74   updated, insert
304d0 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a  ed or deleted..*
304e0 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  * ^Any callback 
304f0 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
30500 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66  s call to this f
30510 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74  unction.** for t
30520 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
30530 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
30540 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a  verridden..**.**
30550 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
30560 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
30570 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69  er to the functi
30580 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65  on to invoke whe
30590 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70  n a.** row is up
305a0 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
305b0 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e  or deleted..** ^
305c0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
305d0 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  nt to the callba
305e0 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
305f0 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
30600 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  nt.** to sqlite3
30610 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a  _update_hook()..
30620 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 63  ** ^The second c
30630 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74  allback argument
30640 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
30650 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c  TE_INSERT], [SQL
30660 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20  ITE_DELETE],.** 
30670 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54  or [SQLITE_UPDAT
30680 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  E], depending on
30690 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74   the operation t
306a0 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63  hat caused the c
306b0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65  allback.** to be
306c0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68   invoked..** ^Th
306d0 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
306e0 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  th arguments to 
306f0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  the callback con
30700 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f  tain pointers to
30710 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
30720 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 20   and table name 
30730 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
30740 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20  ffected row..** 
30750 5e 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62  ^The final callb
30760 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ack parameter is
30770 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
30780 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20  the row..** ^In 
30790 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75  the case of an u
307a0 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74  pdate, this is t
307b0 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65 72  he [rowid] after
307c0 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65   the update take
307d0 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  s place..**.** ^
307e0 28 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b  (The update hook
307f0 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
30800 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79  when internal sy
30810 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a  stem tables are.
30820 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65  ** modified (i.e
30830 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20  . sqlite_master 
30840 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65  and sqlite_seque
30850 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  nce).)^.**.** ^I
30860 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  n the current im
30870 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68  plementation, th
30880 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a  e update hook.**
30890 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
308a0 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e  when duplication
308b0 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
308c0 64 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e 0a  d because of an.
308d0 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20  ** [ON CONFLICT 
308e0 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45  | ON CONFLICT RE
308f0 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20 20  PLACE] clause.  
30900 5e 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64 61  ^Nor is the upda
30910 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b  te hook.** invok
30920 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72 65  ed when rows are
30930 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 74   deleted using t
30940 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  he [truncate opt
30950 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  imization]..** T
30960 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64 65  he exceptions de
30970 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70 61  fined in this pa
30980 72 61 67 72 61 70 68 20 6d 69 67 68 74 20 63 68  ragraph might ch
30990 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65  ange in a future
309a0 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53  .** release of S
309b0 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
309c0 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70   update hook imp
309d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
309e0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
309f0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
30a00 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
30a10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
30a20 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70  t invoked the up
30a30 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20  date hook.  Any 
30a40 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f  actions.** to mo
30a50 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
30a60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
30a70 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e  t be deferred un
30a80 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a  til after the.**
30a90 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74   completion of t
30aa0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
30ab0 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ()] call that tr
30ac0 69 67 67 65 72 65 64 20 74 68 65 20 75 70 64 61  iggered the upda
30ad0 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65  te hook..** Note
30ae0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
30af0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
30b00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
30b10 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
30b20 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
30b30 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
30b40 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
30b50 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
30b60 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
30b70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70   ^The sqlite3_up
30b80 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  date_hook(D,C,P)
30b90 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 74   function.** ret
30ba0 75 72 6e 73 20 74 68 65 20 50 20 61 72 67 75 6d  urns the P argum
30bb0 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65  ent from the pre
30bc0 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e  vious call.** on
30bd0 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
30be0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
30bf0 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a  D, or NULL for.*
30c00 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  * the first call
30c10 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   on D..**.** See
30c20 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
30c30 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
30c40 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
30c50 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a  ollback_hook()].
30c60 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  ** interfaces..*
30c70 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
30c80 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73  update_hook(.  s
30c90 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
30ca0 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c  (*)(void *,int ,
30cb0 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61  char const *,cha
30cc0 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65  r const *,sqlite
30cd0 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64  3_int64),.  void
30ce0 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *.);../*.** CAPI
30cf0 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
30d00 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50  Disable Shared P
30d10 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 20 4b 45  ager Cache.** KE
30d20 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20  YWORDS: {shared 
30d30 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54  cache}.**.** ^(T
30d40 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  his routine enab
30d50 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
30d60 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74  the sharing of t
30d70 68 65 20 64 61 74 61 62 61 73 65 20 63 61 63 68  he database cach
30d80 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20  e.** and schema 
30d90 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
30da0 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73  between [databas
30db0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63  e connection | c
30dc0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74  onnections].** t
30dd0 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  o the same datab
30de0 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20  ase. Sharing is 
30df0 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61  enabled if the a
30e00 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a  rgument is true.
30e10 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20  ** and disabled 
30e20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  if the argument 
30e30 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a  is false.)^.**.*
30e40 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69 6e 67  * ^Cache sharing
30e50 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20   is enabled and 
30e60 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20  disabled for an 
30e70 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a  entire process..
30e80 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61  ** This is a cha
30e90 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65  nge as of SQLite
30ea0 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20   version 3.5.0. 
30eb0 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e  In prior version
30ec0 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20  s of SQLite,.** 
30ed0 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62  sharing was enab
30ee0 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20  led or disabled 
30ef0 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20  for each thread 
30f00 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
30f10 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20 73 68  * ^(The cache sh
30f20 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62  aring mode set b
30f30 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  y this interface
30f40 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62   effects all sub
30f50 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
30f60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
30f70 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
30f80 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b  pen_v2()], and [
30f90 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
30fa0 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64  ]..** Existing d
30fb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30fc0 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65  ons continue use
30fd0 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64   the sharing mod
30fe0 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e  e.** that was in
30ff0 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74   effect at the t
31000 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70  ime they were op
31010 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  ened.)^.**.** ^(
31020 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
31030 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
31040 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65   if shared cache
31050 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20   was enabled or 
31060 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63  disabled.** succ
31070 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65  essfully.  An [e
31080 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
31090 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65  turned otherwise
310a0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65  .)^.**.** ^Share
310b0 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62  d cache is disab
310c0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20  led by default. 
310d0 42 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63  But this might c
310e0 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75  hange in.** futu
310f0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
31100 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74  QLite.  Applicat
31110 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61  ions that care a
31120 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63  bout shared.** c
31130 61 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f  ache setting sho
31140 75 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69  uld set it expli
31150 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  citly..**.** See
31160 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20   Also:  [SQLite 
31170 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f 64  Shared-Cache Mod
31180 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e].*/.int sqlite
31190 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
311a0 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  cache(int);../*.
311b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74 74  ** CAPI3REF: Att
311c0 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61  empt To Free Hea
311d0 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e  p Memory.**.** ^
311e0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  The sqlite3_rele
311f0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74  ase_memory() int
31200 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
31210 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a  to free N bytes.
31220 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  ** of heap memor
31230 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e  y by deallocatin
31240 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20  g non-essential 
31250 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
31260 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68  ns.** held by th
31270 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61  e database libra
31280 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73 65  ry.   Memory use
31290 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62  d to cache datab
312a0 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20  ase.** pages to 
312b0 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
312c0 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c  nce is an exampl
312d0 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69  e of non-essenti
312e0 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73  al memory..** ^s
312f0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
31300 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20  emory() returns 
31310 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
31320 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65  tes actually fre
31330 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67  ed,.** which mig
31340 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65  ht be more or le
31350 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75  ss than the amou
31360 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a  nt requested..**
31370 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
31380 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72  lease_memory() r
31390 6f 75 74 69 6e 65 20 69 73 20 61 20 6e 6f 2d 6f  outine is a no-o
313a0 70 20 72 65 74 75 72 6e 69 6e 67 20 7a 65 72 6f  p returning zero
313b0 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
313c0 20 6e 6f 74 20 63 6f 6d 70 69 6c 65 64 20 77 69   not compiled wi
313d0 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  th [SQLITE_ENABL
313e0 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d  E_MEMORY_MANAGEM
313f0 45 4e 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ENT]..*/.int sql
31400 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
31410 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  ory(int);../*.**
31420 20 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73   CAPI3REF: Impos
31430 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61  e A Limit On Hea
31440 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68  p Size.**.** ^Th
31450 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  e sqlite3_soft_h
31460 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 69 6e  eap_limit64() in
31470 74 65 72 66 61 63 65 20 73 65 74 73 20 61 6e 64  terface sets and
31480 2f 6f 72 20 71 75 65 72 69 65 73 20 74 68 65 0a  /or queries the.
31490 2a 2a 20 73 6f 66 74 20 6c 69 6d 69 74 20 6f 6e  ** soft limit on
314a0 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68   the amount of h
314b0 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  eap memory that 
314c0 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64  may be allocated
314d0 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e   by SQLite..** ^
314e0 53 51 4c 69 74 65 20 73 74 72 69 76 65 73 20 74  SQLite strives t
314f0 6f 20 6b 65 65 70 20 68 65 61 70 20 6d 65 6d 6f  o keep heap memo
31500 72 79 20 75 74 69 6c 69 7a 61 74 69 6f 6e 20 62  ry utilization b
31510 65 6c 6f 77 20 74 68 65 20 73 6f 66 74 20 68 65  elow the soft he
31520 61 70 0a 2a 2a 20 6c 69 6d 69 74 20 62 79 20 72  ap.** limit by r
31530 65 64 75 63 69 6e 67 20 74 68 65 20 6e 75 6d 62  educing the numb
31540 65 72 20 6f 66 20 70 61 67 65 73 20 68 65 6c 64  er of pages held
31550 20 69 6e 20 74 68 65 20 70 61 67 65 20 63 61 63   in the page cac
31560 68 65 0a 2a 2a 20 61 73 20 68 65 61 70 20 6d 65  he.** as heap me
31570 6d 6f 72 79 20 75 73 61 67 65 73 20 61 70 70 72  mory usages appr
31580 6f 61 63 68 65 73 20 74 68 65 20 6c 69 6d 69 74  oaches the limit
31590 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f 66 74 20 68  ..** ^The soft h
315a0 65 61 70 20 6c 69 6d 69 74 20 69 73 20 22 73 6f  eap limit is "so
315b0 66 74 22 20 62 65 63 61 75 73 65 20 65 76 65 6e  ft" because even
315c0 20 74 68 6f 75 67 68 20 53 51 4c 69 74 65 20 73   though SQLite s
315d0 74 72 69 76 65 73 20 74 6f 20 73 74 61 79 0a 2a  trives to stay.*
315e0 2a 20 62 65 6c 6f 77 20 74 68 65 20 6c 69 6d 69  * below the limi
315f0 74 2c 20 69 74 20 77 69 6c 6c 20 65 78 63 65 65  t, it will excee
31600 64 20 74 68 65 20 6c 69 6d 69 74 20 72 61 74 68  d the limit rath
31610 65 72 20 74 68 61 6e 20 67 65 6e 65 72 61 74 65  er than generate
31620 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  .** an [SQLITE_N
31630 4f 4d 45 4d 5d 20 65 72 72 6f 72 2e 20 20 49 6e  OMEM] error.  In
31640 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
31650 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
31660 74 20 0a 2a 2a 20 69 73 20 61 64 76 69 73 6f 72  t .** is advisor
31670 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y only..**.** ^T
31680 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
31690 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 73 6f 66  from sqlite3_sof
316a0 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
316b0 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a   is the size of.
316c0 2a 2a 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  ** the soft heap
316d0 20 6c 69 6d 69 74 20 70 72 69 6f 72 20 74 6f 20   limit prior to 
316e0 74 68 65 20 63 61 6c 6c 2e 20 20 5e 49 66 20 74  the call.  ^If t
316f0 68 65 20 61 72 67 75 6d 65 6e 74 20 4e 20 69 73  he argument N is
31700 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 74 68 65   negative.** the
31710 6e 20 6e 6f 20 63 68 61 6e 67 65 20 69 73 20 6d  n no change is m
31720 61 64 65 20 74 6f 20 74 68 65 20 73 6f 66 74 20  ade to the soft 
31730 68 65 61 70 20 6c 69 6d 69 74 2e 20 20 48 65 6e  heap limit.  Hen
31740 63 65 2c 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ce, the current.
31750 2a 2a 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73  ** size of the s
31760 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63  oft heap limit c
31770 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
31780 20 62 79 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   by invoking.** 
31790 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
317a0 70 5f 6c 69 6d 69 74 36 34 28 29 20 77 69 74 68  p_limit64() with
317b0 20 61 20 6e 65 67 61 74 69 76 65 20 61 72 67 75   a negative argu
317c0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ment..**.** ^If 
317d0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 4e 20 69  the argument N i
317e0 73 20 7a 65 72 6f 20 74 68 65 6e 20 74 68 65 20  s zero then the 
317f0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
31800 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  is disabled..**.
31810 2a 2a 20 5e 28 54 68 65 20 73 6f 66 74 20 68 65  ** ^(The soft he
31820 61 70 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20  ap limit is not 
31830 65 6e 66 6f 72 63 65 64 20 69 6e 20 74 68 65 20  enforced in the 
31840 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
31850 74 61 74 69 6f 6e 0a 2a 2a 20 69 66 20 6f 6e 65  tation.** if one
31860 20 6f 72 20 6d 6f 72 65 20 6f 66 20 66 6f 6c 6c   or more of foll
31870 6f 77 69 6e 67 20 63 6f 6e 64 69 74 69 6f 6e 73  owing conditions
31880 20 61 72 65 20 74 72 75 65 3a 0a 2a 2a 0a 2a 2a   are true:.**.**
31890 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
318a0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
318b0 74 20 69 73 20 73 65 74 20 74 6f 20 7a 65 72 6f  t is set to zero
318c0 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d 65 6d 6f 72 79  ..** <li> Memory
318d0 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 73 20 64   accounting is d
318e0 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20  isabled using a 
318f0 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 74  combination of t
31900 68 65 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69  he.**      [sqli
31910 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
31920 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
31930 41 54 55 53 5d 2c 2e 2e 2e 29 20 73 74 61 72 74  ATUS],...) start
31940 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 61 6e 64  -time option and
31950 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 5b 53 51  .**      the [SQ
31960 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
31970 53 54 41 54 55 53 5d 20 63 6f 6d 70 69 6c 65 2d  STATUS] compile-
31980 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
31990 3c 6c 69 3e 20 41 6e 20 61 6c 74 65 72 6e 61 74  <li> An alternat
319a0 69 76 65 20 70 61 67 65 20 63 61 63 68 65 20 69  ive page cache i
319b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
319c0 20 73 70 65 63 69 66 65 64 20 75 73 69 6e 67 0a   specifed using.
319d0 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33  **      [sqlite3
319e0 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
319f0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 2c  _CONFIG_PCACHE],
31a00 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ...)..** <li> Th
31a10 65 20 70 61 67 65 20 63 61 63 68 65 20 61 6c 6c  e page cache all
31a20 6f 63 61 74 65 73 20 66 72 6f 6d 20 69 74 73 20  ocates from its 
31a30 6f 77 6e 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 20  own memory pool 
31a40 73 75 70 70 6c 69 65 64 0a 2a 2a 20 20 20 20 20  supplied.**     
31a50 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   by [sqlite3_con
31a60 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
31a70 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2c 2e  FIG_PAGECACHE],.
31a80 2e 2e 29 20 72 61 74 68 65 72 20 74 68 61 6e 0a  ..) rather than.
31a90 2a 2a 20 20 20 20 20 20 66 72 6f 6d 20 74 68 65  **      from the
31aa0 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29   heap..** </ul>)
31ab0 5e 0a 2a 2a 0a 2a 2a 20 42 65 67 69 6e 6e 69 6e  ^.**.** Beginnin
31ac0 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 76 65  g with SQLite ve
31ad0 72 73 69 6f 6e 20 33 2e 37 2e 33 2c 20 74 68 65  rsion 3.7.3, the
31ae0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
31af0 20 69 73 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20   is enforced.** 
31b00 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
31b10 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
31b20 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
31b30 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e  MEMORY_MANAGEMEN
31b40 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
31b50 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 76  me option is inv
31b60 6f 6b 65 64 2e 20 20 57 69 74 68 20 5b 53 51 4c  oked.  With [SQL
31b70 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52  ITE_ENABLE_MEMOR
31b80 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 0a 2a  Y_MANAGEMENT],.*
31b90 2a 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  * the soft heap 
31ba0 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63 65  limit is enforce
31bb0 64 20 6f 6e 20 65 76 65 72 79 20 6d 65 6d 6f 72  d on every memor
31bc0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 57  y allocation.  W
31bd0 69 74 68 6f 75 74 0a 2a 2a 20 5b 53 51 4c 49 54  ithout.** [SQLIT
31be0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f  E_ENABLE_MEMORY_
31bf0 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 20 74 68 65  MANAGEMENT], the
31c00 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
31c10 20 69 73 20 6f 6e 6c 79 20 65 6e 66 6f 72 63 65   is only enforce
31c20 64 0a 2a 2a 20 77 68 65 6e 20 6d 65 6d 6f 72 79  d.** when memory
31c30 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 62 79   is allocated by
31c40 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65 2e   the page cache.
31c50 20 20 54 65 73 74 69 6e 67 20 73 75 67 67 65 73    Testing sugges
31c60 74 73 20 74 68 61 74 20 62 65 63 61 75 73 65 0a  ts that because.
31c70 2a 2a 20 74 68 65 20 70 61 67 65 20 63 61 63 68  ** the page cach
31c80 65 20 69 73 20 74 68 65 20 70 72 65 64 6f 6d 69  e is the predomi
31c90 6e 61 74 65 20 6d 65 6d 6f 72 79 20 75 73 65 72  nate memory user
31ca0 20 69 6e 20 53 51 4c 69 74 65 2c 20 6d 6f 73 74   in SQLite, most
31cb0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
31cc0 20 77 69 6c 6c 20 61 63 68 69 65 76 65 20 61 64   will achieve ad
31cd0 65 71 75 61 74 65 20 73 6f 66 74 20 68 65 61 70  equate soft heap
31ce0 20 6c 69 6d 69 74 20 65 6e 66 6f 72 63 65 6d 65   limit enforceme
31cf0 6e 74 20 77 69 74 68 6f 75 74 0a 2a 2a 20 74 68  nt without.** th
31d00 65 20 75 73 65 20 6f 66 20 5b 53 51 4c 49 54 45  e use of [SQLITE
31d10 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d  _ENABLE_MEMORY_M
31d20 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a  ANAGEMENT]..**.*
31d30 2a 20 54 68 65 20 63 69 72 63 75 6d 73 74 61 6e  * The circumstan
31d40 63 65 73 20 75 6e 64 65 72 20 77 68 69 63 68 20  ces under which 
31d50 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 6e 66 6f  SQLite will enfo
31d60 72 63 65 20 74 68 65 20 73 6f 66 74 20 68 65 61  rce the soft hea
31d70 70 20 6c 69 6d 69 74 20 6d 61 79 0a 2a 2a 20 63  p limit may.** c
31d80 68 61 6e 67 65 73 20 69 6e 20 66 75 74 75 72 65  hanges in future
31d90 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
31da0 69 74 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  ite..*/.sqlite3_
31db0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 73 6f  int64 sqlite3_so
31dc0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
31dd0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 4e 29  sqlite3_int64 N)
31de0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31df0 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 53 6f  F: Deprecated So
31e00 66 74 20 48 65 61 70 20 4c 69 6d 69 74 20 49 6e  ft Heap Limit In
31e10 74 65 72 66 61 63 65 0a 2a 2a 20 44 45 50 52 45  terface.** DEPRE
31e20 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 69 73  CATED.**.** This
31e30 20 69 73 20 61 20 64 65 70 72 65 63 61 74 65 64   is a deprecated
31e40 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
31e50 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
31e60 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a  ap_limit64()].**
31e70 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 69   interface.  Thi
31e80 73 20 72 6f 75 74 69 6e 65 20 69 73 20 70 72 6f  s routine is pro
31e90 76 69 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72  vided for histor
31ea0 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
31eb0 74 79 0a 2a 2a 20 6f 6e 6c 79 2e 20 20 41 6c 6c  ty.** only.  All
31ec0 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
31ed0 73 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65  s should use the
31ee0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  .** [sqlite3_sof
31ef0 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
31f00 5d 20 69 6e 74 65 72 66 61 63 65 20 72 61 74 68  ] interface rath
31f10 65 72 20 74 68 61 6e 20 74 68 69 73 20 6f 6e 65  er than this one
31f20 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52  ..*/.SQLITE_DEPR
31f30 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69  ECATED void sqli
31f40 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
31f50 6d 69 74 28 69 6e 74 20 4e 29 3b 0a 0a 0a 2f 2a  mit(int N);.../*
31f60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78  .** CAPI3REF: Ex
31f70 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20 41  tract Metadata A
31f80 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66  bout A Column Of
31f90 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e   A Table.**.** ^
31fa0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
31fb0 75 72 6e 73 20 6d 65 74 61 64 61 74 61 20 61 62  urns metadata ab
31fc0 6f 75 74 20 61 20 73 70 65 63 69 66 69 63 20 63  out a specific c
31fd0 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69  olumn of a speci
31fe0 66 69 63 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  fic.** database 
31ff0 74 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65  table accessible
32000 20 75 73 69 6e 67 20 74 68 65 20 5b 64 61 74 61   using the [data
32010 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
32020 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65   handle.** passe
32030 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 66  d as the first f
32040 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
32050 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c  ..**.** ^The col
32060 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65  umn is identifie
32070 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c  d by the second,
32080 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
32090 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 0a  h parameters to.
320a0 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** this function
320b0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
320c0 72 61 6d 65 74 65 72 20 69 73 20 65 69 74 68 65  rameter is eithe
320d0 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  r the name of th
320e0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69  e database.** (i
320f0 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d  .e. "main", "tem
32100 70 22 2c 20 6f 72 20 61 6e 20 61 74 74 61 63 68  p", or an attach
32110 65 64 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e  ed database) con
32120 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63  taining the spec
32130 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f  ified.** table o
32140 72 20 4e 55 4c 4c 2e 20 5e 49 66 20 69 74 20 69  r NULL. ^If it i
32150 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c  s NULL, then all
32160 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
32170 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65 64  ses are searched
32180 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c  .** for the tabl
32190 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
321a0 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64 20   algorithm used 
321b0 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  by the database 
321c0 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73  engine to.** res
321d0 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64  olve unqualified
321e0 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65   table reference
321f0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  s..**.** ^The th
32200 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
32210 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
32220 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74  s function are t
32230 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c  he table and col
32240 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74  umn.** name of t
32250 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d  he desired colum
32260 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
32270 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73   Neither of thes
32280 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  e parameters.** 
32290 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  may be NULL..**.
322a0 2a 2a 20 5e 4d 65 74 61 64 61 74 61 20 69 73 20  ** ^Metadata is 
322b0 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74  returned by writ
322c0 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ing to the memor
322d0 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73  y locations pass
322e0 65 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a  ed as the 5th.**
322f0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
32300 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
32310 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 41 6e  is function. ^An
32320 79 20 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d  y of these argum
32330 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e  ents may be.** N
32340 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61  ULL, in which ca
32350 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  se the correspon
32360 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20  ding element of 
32370 6d 65 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74  metadata is omit
32380 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c  ted..**.** ^(<bl
32390 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
323a0 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
323b0 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61  ** <tr><th> Para
323c0 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75 74 70 75  meter <th> Outpu
323d0 74 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  t<br>Type <th>  
323e0 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a  Description.**.*
323f0 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c  * <tr><td> 5th <
32400 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20  td> const char* 
32410 3c 74 64 3e 20 44 61 74 61 20 74 79 70 65 0a 2a  <td> Data type.*
32420 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c  * <tr><td> 6th <
32430 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20  td> const char* 
32440 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66  <td> Name of def
32450 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ault collation s
32460 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c  equence.** <tr><
32470 74 64 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e 74  td> 7th <td> int
32480 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72           <td> Tr
32490 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73  ue if column has
324a0 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73   a NOT NULL cons
324b0 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74  traint.** <tr><t
324c0 64 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e 74 20  d> 8th <td> int 
324d0 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75          <td> Tru
324e0 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70  e if column is p
324f0 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41  art of the PRIMA
32500 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74  RY KEY.** <tr><t
32510 64 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e 74 20  d> 9th <td> int 
32520 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75          <td> Tru
32530 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b  e if column is [
32540 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a  AUTOINCREMENT].*
32550 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
32560 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
32570 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
32580 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
32590 65 20 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e  e character poin
325a0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f  ters returned fo
325b0 72 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61  r the.** declara
325c0 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f  tion type and co
325d0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
325e0 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75   is valid only u
325f0 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a  ntil the next.**
32600 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c   call to any SQL
32610 69 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e  ite API function
32620 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
32630 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65 20  specified table 
32640 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69  is actually a vi
32650 65 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ew, an [error co
32660 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
32670 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  .**.** ^If the s
32680 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20  pecified column 
32690 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64  is "rowid", "oid
326a0 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61  " or "_rowid_" a
326b0 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45  nd an.** [INTEGE
326c0 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63  R PRIMARY KEY] c
326d0 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65  olumn has been e
326e0 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
326f0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74  ed, then the out
32700 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  put.** parameter
32710 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68  s are set for th
32720 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  e explicitly dec
32730 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 5e 28  lared column. ^(
32740 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a  If there is no.*
32750 2a 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  * explicitly dec
32760 6c 61 72 65 64 20 5b 49 4e 54 45 47 45 52 20 50  lared [INTEGER P
32770 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75  RIMARY KEY] colu
32780 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74  mn, then the out
32790 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  put.** parameter
327a0 73 20 61 72 65 20 73 65 74 20 61 73 20 66 6f 6c  s are set as fol
327b0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65  lows:.**.** <pre
327c0 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79  >.**     data ty
327d0 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a  pe: "INTEGER".**
327e0 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73       collation s
327f0 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59  equence: "BINARY
32800 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c  ".**     not nul
32810 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d  l: 0.**     prim
32820 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20  ary key: 1.**   
32830 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74    auto increment
32840 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a  : 0.** </pre>)^.
32850 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e  **.** ^(This fun
32860 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f  ction may load o
32870 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d  ne or more schem
32880 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65  as from database
32890 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a   files. If an.**
328a0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
328b0 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73  ring this proces
328c0 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 71  s, or if the req
328d0 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20  uested table or 
328e0 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74  column.** cannot
328f0 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65   be found, an [e
32900 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
32910 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72  turned and an er
32920 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66 74  ror message left
32930 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74 61  .** in the [data
32940 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
32950 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76 65   (to be retrieve
32960 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f  d using sqlite3_
32970 65 72 72 6d 73 67 28 29 29 2e 29 5e 0a 2a 2a 0a  errmsg()).)^.**.
32980 2a 2a 20 5e 54 68 69 73 20 41 50 49 20 69 73 20  ** ^This API is 
32990 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
329a0 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
329b0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
329c0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
329d0 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
329e0 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
329f0 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66  essor symbol def
32a00 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
32a10 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d  ite3_table_colum
32a20 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71  n_metadata(.  sq
32a30 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
32a40 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e            /* Con
32a50 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a  nection handle *
32a60 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
32a70 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20  zDbName,        
32a80 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65  /* Database name
32a90 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f   or NULL */.  co
32aa0 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65  nst char *zTable
32ab0 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62  Name,     /* Tab
32ac0 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e  le name */.  con
32ad0 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e  st char *zColumn
32ae0 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75  Name,    /* Colu
32af0 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61  mn name */.  cha
32b00 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61  r const **pzData
32b10 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50  Type,    /* OUTP
32b20 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74  UT: Declared dat
32b30 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72  a type */.  char
32b40 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53   const **pzCollS
32b50 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55  eq,     /* OUTPU
32b60 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  T: Collation seq
32b70 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20  uence name */.  
32b80 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20  int *pNotNull,  
32b90 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f              /* O
32ba0 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e  UTPUT: True if N
32bb0 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69  OT NULL constrai
32bc0 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69  nt exists */.  i
32bd0 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c  nt *pPrimaryKey,
32be0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
32bf0 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f  TPUT: True if co
32c00 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20  lumn part of PK 
32c10 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69  */.  int *pAutoi
32c20 6e 63 20 20 20 20 20 20 20 20 20 20 20 20 20 20  nc              
32c30 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
32c40 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75   if column is au
32c50 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a  to-increment */.
32c60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
32c70 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65  EF: Load An Exte
32c80 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  nsion.**.** ^Thi
32c90 73 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64  s interface load
32ca0 73 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65  s an SQLite exte
32cb0 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72  nsion library fr
32cc0 6f 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c  om the named fil
32cd0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e..**.** ^The sq
32ce0 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
32cf0 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65  sion() interface
32d00 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61   attempts to loa
32d10 64 20 61 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 65  d an.** SQLite e
32d20 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79  xtension library
32d30 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68   contained in th
32d40 65 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a  e file zFile..**
32d50 0a 2a 2a 20 5e 54 68 65 20 65 6e 74 72 79 20 70  .** ^The entry p
32d60 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 0a 2a  oint is zProc..*
32d70 2a 20 5e 7a 50 72 6f 63 20 6d 61 79 20 62 65 20  * ^zProc may be 
32d80 30 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  0, in which case
32d90 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
32da0 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20   entry point.** 
32db0 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71 6c  defaults to "sql
32dc0 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69  ite3_extension_i
32dd0 6e 69 74 22 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  nit"..** ^The sq
32de0 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
32df0 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65  sion() interface
32e00 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
32e10 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
32e20 73 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45  ss and [SQLITE_E
32e30 52 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69  RROR] if somethi
32e40 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
32e50 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f  * ^If an error o
32e60 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d  ccurs and pzErrM
32e70 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65  sg is not 0, the
32e80 6e 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  n the.** [sqlite
32e90 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
32ea0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68  ()] interface sh
32eb0 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a  all attempt to.*
32ec0 2a 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67  * fill *pzErrMsg
32ed0 20 77 69 74 68 20 65 72 72 6f 72 20 6d 65 73 73   with error mess
32ee0 61 67 65 20 74 65 78 74 20 73 74 6f 72 65 64 20  age text stored 
32ef0 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74  in memory.** obt
32f00 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
32f10 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 54  te3_malloc()]. T
32f20 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
32f30 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 66 72  ion.** should fr
32f40 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 20 62  ee this memory b
32f50 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
32f60 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
32f70 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  * ^Extension loa
32f80 64 69 6e 67 20 6d 75 73 74 20 62 65 20 65 6e 61  ding must be ena
32f90 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  bled using.** [s
32fa0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
32fb0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
32fc0 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
32fd0 20 74 68 69 73 20 41 50 49 2c 0a 2a 2a 20 6f 74   this API,.** ot
32fe0 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
32ff0 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65   will be returne
33000 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
33010 6f 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65  o the [load_exte
33020 6e 73 69 6f 6e 28 29 20 53 51 4c 20 66 75 6e 63  nsion() SQL func
33030 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  tion]..*/.int sq
33040 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
33050 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  sion(.  sqlite3 
33060 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
33070 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e 73   Load the extens
33080 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 61  ion into this da
33090 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
330a0 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  n */.  const cha
330b0 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20  r *zFile,    /* 
330c0 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61 72  Name of the shar
330d0 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61  ed library conta
330e0 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20  ining extension 
330f0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
33100 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e  *zProc,    /* En
33110 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 69  try point.  Deri
33120 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69  ved from zFile i
33130 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  f 0 */.  char **
33140 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20 2f  pzErrMsg       /
33150 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73 73  * Put error mess
33160 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74 20  age here if not 
33170 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  0 */.);../*.** C
33180 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
33190 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
331a0 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a  sion Loading.**.
331b0 2a 2a 20 5e 53 6f 20 61 73 20 6e 6f 74 20 74 6f  ** ^So as not to
331c0 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20 68   open security h
331d0 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 70  oles in older ap
331e0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
331f0 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65  are.** unprepare
33200 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 65  d to deal with e
33210 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
33220 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e 73  , and as a means
33230 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a   of disabling.**
33240 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69   extension loadi
33250 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74  ng while evaluat
33260 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65 64  ing user-entered
33270 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77   SQL, the follow
33280 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20 70 72  ing API.** is pr
33290 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20 74  ovided to turn t
332a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64  he [sqlite3_load
332b0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65  _extension()] me
332c0 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 20 6f  chanism on and o
332d0 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e  ff..**.** ^Exten
332e0 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20  sion loading is 
332f0 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 20  off by default. 
33300 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 36 33  See ticket #1863
33310 2e 0a 2a 2a 20 5e 43 61 6c 6c 20 74 68 65 20 73  ..** ^Call the s
33320 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
33330 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 72  ad_extension() r
33340 6f 75 74 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66  outine with onof
33350 66 3d 3d 31 0a 2a 2a 20 74 6f 20 74 75 72 6e 20  f==1.** to turn 
33360 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
33370 67 20 6f 6e 20 61 6e 64 20 63 61 6c 6c 20 69 74  g on and call it
33380 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 74   with onoff==0 t
33390 6f 20 74 75 72 6e 0a 2a 2a 20 69 74 20 62 61 63  o turn.** it bac
333a0 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2f 0a  k off again..*/.
333b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62  int sqlite3_enab
333c0 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
333d0 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 69  n(sqlite3 *db, i
333e0 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
333f0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 6f  * CAPI3REF: Auto
33400 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20 53  matically Load S
33410 74 61 74 69 63 61 6c 6c 79 20 4c 69 6e 6b 65 64  tatically Linked
33420 20 45 78 74 65 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a   Extensions.**.*
33430 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
33440 65 20 63 61 75 73 65 73 20 74 68 65 20 78 45 6e  e causes the xEn
33450 74 72 79 50 6f 69 6e 74 28 29 20 66 75 6e 63 74  tryPoint() funct
33460 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ion to be invoke
33470 64 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 6e 65  d for.** each ne
33480 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  w [database conn
33490 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 69 73 20  ection] that is 
334a0 63 72 65 61 74 65 64 2e 20 20 54 68 65 20 69 64  created.  The id
334b0 65 61 20 68 65 72 65 20 69 73 20 74 68 61 74 0a  ea here is that.
334c0 2a 2a 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29  ** xEntryPoint()
334d0 20 69 73 20 74 68 65 20 65 6e 74 72 79 20 70 6f   is the entry po
334e0 69 6e 74 20 66 6f 72 20 61 20 73 74 61 74 69 63  int for a static
334f0 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 53 51 4c 69  ally linked SQLi
33500 74 65 20 65 78 74 65 6e 73 69 6f 6e 0a 2a 2a 20  te extension.** 
33510 74 68 61 74 20 69 73 20 74 6f 20 62 65 20 61 75  that is to be au
33520 74 6f 6d 61 74 69 63 61 6c 6c 79 20 6c 6f 61 64  tomatically load
33530 65 64 20 69 6e 74 6f 20 61 6c 6c 20 6e 65 77 20  ed into all new 
33540 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33550 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  ions..**.** ^(Ev
33560 65 6e 20 74 68 6f 75 67 68 20 74 68 65 20 66 75  en though the fu
33570 6e 63 74 69 6f 6e 20 70 72 6f 74 6f 74 79 70 65  nction prototype
33580 20 73 68 6f 77 73 20 74 68 61 74 20 78 45 6e 74   shows that xEnt
33590 72 79 50 6f 69 6e 74 28 29 20 74 61 6b 65 73 0a  ryPoint() takes.
335a0 2a 2a 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  ** no arguments 
335b0 61 6e 64 20 72 65 74 75 72 6e 73 20 76 6f 69 64  and returns void
335c0 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  , SQLite invokes
335d0 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 77   xEntryPoint() w
335e0 69 74 68 20 74 68 72 65 65 0a 2a 2a 20 61 72 67  ith three.** arg
335f0 75 6d 65 6e 74 73 20 61 6e 64 20 65 78 70 65 63  uments and expec
33600 74 73 20 61 6e 64 20 69 6e 74 65 67 65 72 20 72  ts and integer r
33610 65 73 75 6c 74 20 61 73 20 69 66 20 74 68 65 20  esult as if the 
33620 73 69 67 6e 61 74 75 72 65 20 6f 66 20 74 68 65  signature of the
33630 0a 2a 2a 20 65 6e 74 72 79 20 70 6f 69 6e 74 20  .** entry point 
33640 77 68 65 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73  where as follows
33650 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
33660 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 26 6e 62  ote><pre>.** &nb
33670 73 70 3b 20 20 69 6e 74 20 78 45 6e 74 72 79 50  sp;  int xEntryP
33680 6f 69 6e 74 28 0a 2a 2a 20 26 6e 62 73 70 3b 20  oint(.** &nbsp; 
33690 20 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a     sqlite3 *db,.
336a0 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 63 6f 6e  ** &nbsp;    con
336b0 73 74 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d  st char **pzErrM
336c0 73 67 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20  sg,.** &nbsp;   
336d0 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
336e0 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e  lite3_api_routin
336f0 65 73 20 2a 70 54 68 75 6e 6b 0a 2a 2a 20 26 6e  es *pThunk.** &n
33700 62 73 70 3b 20 20 29 3b 0a 2a 2a 20 3c 2f 70 72  bsp;  );.** </pr
33710 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
33720 5e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 78  ^.**.** If the x
33730 45 6e 74 72 79 50 6f 69 6e 74 20 72 6f 75 74 69  EntryPoint routi
33740 6e 65 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e  ne encounters an
33750 20 65 72 72 6f 72 2c 20 69 74 20 73 68 6f 75 6c   error, it shoul
33760 64 20 6d 61 6b 65 20 2a 70 7a 45 72 72 4d 73 67  d make *pzErrMsg
33770 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  .** point to an 
33780 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f  appropriate erro
33790 72 20 6d 65 73 73 61 67 65 20 28 6f 62 74 61 69  r message (obtai
337a0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
337b0 33 5f 6d 70 72 69 6e 74 66 28 29 5d 29 0a 2a 2a  3_mprintf()]).**
337c0 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 61   and return an a
337d0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
337e0 72 20 63 6f 64 65 5d 2e 20 20 5e 53 51 4c 69 74  r code].  ^SQLit
337f0 65 20 65 6e 73 75 72 65 73 20 74 68 61 74 20 2a  e ensures that *
33800 70 7a 45 72 72 4d 73 67 0a 2a 2a 20 69 73 20 4e  pzErrMsg.** is N
33810 55 4c 4c 20 62 65 66 6f 72 65 20 63 61 6c 6c 69  ULL before calli
33820 6e 67 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69  ng the xEntryPoi
33830 6e 74 28 29 2e 20 20 5e 53 51 4c 69 74 65 20 77  nt().  ^SQLite w
33840 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 5b 73  ill invoke.** [s
33850 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
33860 6e 20 2a 70 7a 45 72 72 4d 73 67 20 61 66 74 65  n *pzErrMsg afte
33870 72 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20  r xEntryPoint() 
33880 72 65 74 75 72 6e 73 2e 20 20 5e 49 66 20 61 6e  returns.  ^If an
33890 79 0a 2a 2a 20 78 45 6e 74 72 79 50 6f 69 6e 74  y.** xEntryPoint
338a0 28 29 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72  () returns an er
338b0 72 6f 72 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  ror, the [sqlite
338c0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
338d0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a  te3_open16()],.*
338e0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
338f0 65 6e 5f 76 32 28 29 5d 20 63 61 6c 6c 20 74 68  en_v2()] call th
33900 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 68 65 20  at provoked the 
33910 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 77 69  xEntryPoint() wi
33920 6c 6c 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  ll fail..**.** ^
33930 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
33940 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 58  auto_extension(X
33950 29 20 77 69 74 68 20 61 6e 20 65 6e 74 72 79 20  ) with an entry 
33960 70 6f 69 6e 74 20 58 20 74 68 61 74 20 69 73 20  point X that is 
33970 61 6c 72 65 61 64 79 0a 2a 2a 20 6f 6e 20 74 68  already.** on th
33980 65 20 6c 69 73 74 20 6f 66 20 61 75 74 6f 6d 61  e list of automa
33990 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69  tic extensions i
339a0 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
339b0 6f 70 2e 20 5e 4e 6f 20 65 6e 74 72 79 20 70 6f  op. ^No entry po
339c0 69 6e 74 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 63  int.** will be c
339d0 61 6c 6c 65 64 20 6d 6f 72 65 20 74 68 61 6e 20  alled more than 
339e0 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 64 61  once for each da
339f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33a00 6e 20 74 68 61 74 20 69 73 20 6f 70 65 6e 65 64  n that is opened
33a10 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
33a20 3a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  : [sqlite3_reset
33a30 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
33a40 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
33a50 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
33a60 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50  n(void (*xEntryP
33a70 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f  oint)(void));../
33a80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
33a90 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45  eset Automatic E
33aa0 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67  xtension Loading
33ab0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
33ac0 65 72 66 61 63 65 20 64 69 73 61 62 6c 65 73 20  erface disables 
33ad0 61 6c 6c 20 61 75 74 6f 6d 61 74 69 63 20 65 78  all automatic ex
33ae0 74 65 6e 73 69 6f 6e 73 20 70 72 65 76 69 6f 75  tensions previou
33af0 73 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  sly.** registere
33b00 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
33b10 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
33b20 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  )]..*/.void sqli
33b30 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65  te3_reset_auto_e
33b40 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a  xtension(void);.
33b50 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72  ./*.** The inter
33b60 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74  face to the virt
33b70 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e  ual-table mechan
33b80 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ism is currently
33b90 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74   considered.** t
33ba0 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61  o be experimenta
33bb0 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63  l.  The interfac
33bc0 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  e might change i
33bd0 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77  n incompatible w
33be0 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  ays..** If this 
33bf0 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72  is a problem for
33c00 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65   you, do not use
33c10 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 61   the interface a
33c20 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a  t this time..**.
33c30 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 74  ** When the virt
33c40 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e  ual-table mechan
33c50 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20  ism stabilizes, 
33c60 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20  we will declare 
33c70 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  the.** interface
33c80 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20   fixed, support 
33c90 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c  it indefinitely,
33ca0 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73   and remove this
33cb0 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a   comment..*/../*
33cc0 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73 20 75  .** Structures u
33cd0 73 65 64 20 62 79 20 74 68 65 20 76 69 72 74 75  sed by the virtu
33ce0 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61  al table interfa
33cf0 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ce.*/.typedef st
33d00 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61  ruct sqlite3_vta
33d10 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62 3b 0a  b sqlite3_vtab;.
33d20 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
33d30 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
33d40 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  o sqlite3_index_
33d50 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 73 74  info;.typedef st
33d60 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61  ruct sqlite3_vta
33d70 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 65 33  b_cursor sqlite3
33d80 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74 79  _vtab_cursor;.ty
33d90 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
33da0 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c 69  ite3_module sqli
33db0 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a  te3_module;../*.
33dc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
33dd0 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a 65 63  tual Table Objec
33de0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  t.** KEYWORDS: s
33df0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 76  qlite3_module {v
33e00 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
33e10 75 6c 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ule}.**.** This 
33e20 73 74 72 75 63 74 75 72 65 2c 20 73 6f 6d 65 74  structure, somet
33e30 69 6d 65 73 20 63 61 6c 6c 65 64 20 61 20 61 20  imes called a a 
33e40 22 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  "virtual table m
33e50 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 64 65 66 69  odule", .** defi
33e60 6e 65 73 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nes the implemen
33e70 74 61 74 69 6f 6e 20 6f 66 20 61 20 5b 76 69 72  tation of a [vir
33e80 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 20 20 0a  tual tables].  .
33e90 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74 75 72  ** This structur
33ea0 65 20 63 6f 6e 73 69 73 74 73 20 6d 6f 73 74 6c  e consists mostl
33eb0 79 20 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f 72  y of methods for
33ec0 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a   the module..**.
33ed0 2a 2a 20 5e 41 20 76 69 72 74 75 61 6c 20 74 61  ** ^A virtual ta
33ee0 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73 20 63 72  ble module is cr
33ef0 65 61 74 65 64 20 62 79 20 66 69 6c 6c 69 6e 67  eated by filling
33f00 20 69 6e 20 61 20 70 65 72 73 69 73 74 65 6e 74   in a persistent
33f10 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
33f20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 61  this structure a
33f30 6e 64 20 70 61 73 73 69 6e 67 20 61 20 70 6f 69  nd passing a poi
33f40 6e 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e 73  nter to that ins
33f50 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b 73 71 6c  tance.** to [sql
33f60 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
33f70 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  le()] or [sqlite
33f80 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f  3_create_module_
33f90 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72  v2()]..** ^The r
33fa0 65 67 69 73 74 72 61 74 69 6f 6e 20 72 65 6d 61  egistration rema
33fb0 69 6e 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  ins valid until 
33fc0 69 74 20 69 73 20 72 65 70 6c 61 63 65 64 20 62  it is replaced b
33fd0 79 20 61 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a  y a different.**
33fe0 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e 74 69 6c   module or until
33ff0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
34000 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c 6f 73 65  onnection] close
34010 73 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 0a  s.  The content.
34020 2a 2a 20 6f 66 20 74 68 69 73 20 73 74 72 75 63  ** of this struc
34030 74 75 72 65 20 6d 75 73 74 20 6e 6f 74 20 63 68  ture must not ch
34040 61 6e 67 65 20 77 68 69 6c 65 20 69 74 20 69 73  ange while it is
34050 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
34060 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62 61 73 65  .** any database
34070 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2f 0a   connection..*/.
34080 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
34090 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56  odule {.  int iV
340a0 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
340b0 78 43 72 65 61 74 65 29 28 73 71 6c 69 74 65 33  xCreate)(sqlite3
340c0 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20  *, void *pAux,. 
340d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
340e0 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68  t argc, const ch
340f0 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a  ar *const*argv,.
34100 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73                 s
34110 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70  qlite3_vtab **pp
34120 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20  VTab, char**);. 
34130 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29   int (*xConnect)
34140 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20  (sqlite3*, void 
34150 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20  *pAux,.         
34160 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
34170 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73  const char *cons
34180 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20  t*argv,.        
34190 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76         sqlite3_v
341a0 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68  tab **ppVTab, ch
341b0 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ar**);.  int (*x
341c0 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69 74  BestIndex)(sqlit
341d0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20  e3_vtab *pVTab, 
341e0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
341f0 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  fo*);.  int (*xD
34200 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74  isconnect)(sqlit
34210 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
34220 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74 72 6f  .  int (*xDestro
34230 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  y)(sqlite3_vtab 
34240 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
34250 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
34260 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c  vtab *pVTab, sql
34270 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
34280 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20 20   **ppCursor);.  
34290 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
342a0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
342b0 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  r*);.  int (*xFi
342c0 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74  lter)(sqlite3_vt
342d0 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20  ab_cursor*, int 
342e0 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68  idxNum, const ch
342f0 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 20 20  ar *idxStr,.    
34300 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
34310 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f 76 61  argc, sqlite3_va
34320 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69  lue **argv);.  i
34330 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71 6c 69  nt (*xNext)(sqli
34340 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
34350 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66 29  );.  int (*xEof)
34360 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
34370 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  rsor*);.  int (*
34380 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33  xColumn)(sqlite3
34390 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73  _vtab_cursor*, s
343a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
343b0 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
343c0 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33 5f 76  Rowid)(sqlite3_v
343d0 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c  tab_cursor*, sql
343e0 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77  ite3_int64 *pRow
343f0 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70  id);.  int (*xUp
34400 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f 76 74  date)(sqlite3_vt
34410 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  ab *, int, sqlit
34420 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c  e3_value **, sql
34430 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20  ite3_int64 *);. 
34440 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28 73   int (*xBegin)(s
34450 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
34460 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ab);.  int (*xSy
34470 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  nc)(sqlite3_vtab
34480 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
34490 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74  (*xCommit)(sqlit
344a0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
344b0 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61  .  int (*xRollba
344c0 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  ck)(sqlite3_vtab
344d0 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
344e0 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29  (*xFindFunction)
344f0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
34500 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20  Vtab, int nArg, 
34510 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
34520 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  e,.             
34530 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 28            void (
34540 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 74 65  **pxFunc)(sqlite
34550 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
34560 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
34570 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
34580 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a 2a 70          void **p
34590 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
345a0 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  Rename)(sqlite3_
345b0 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e  vtab *pVtab, con
345c0 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a  st char *zNew);.
345d0 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
345e0 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c  EF: Virtual Tabl
345f0 65 20 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72  e Indexing Infor
34600 6d 61 74 69 6f 6e 0a 2a 2a 20 4b 45 59 57 4f 52  mation.** KEYWOR
34610 44 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  DS: sqlite3_inde
34620 78 5f 69 6e 66 6f 0a 2a 2a 0a 2a 2a 20 54 68 65  x_info.**.** The
34630 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
34640 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e  nfo structure an
34650 64 20 69 74 73 20 73 75 62 73 74 72 75 63 74 75  d its substructu
34660 72 65 73 20 69 73 20 75 73 65 64 20 61 73 20 70  res is used as p
34670 61 72 74 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76  art.** of the [v
34680 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 69 6e  irtual table] in
34690 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 70 61  terface to.** pa
346a0 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ss information i
346b0 6e 74 6f 20 61 6e 64 20 72 65 63 65 69 76 65 20  nto and receive 
346c0 74 68 65 20 72 65 70 6c 79 20 66 72 6f 6d 20 74  the reply from t
346d0 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 0a  he [xBestIndex].
346e0 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 20 5b  ** method of a [
346f0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
34700 64 75 6c 65 5d 2e 20 20 54 68 65 20 66 69 65 6c  dule].  The fiel
34710 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74  ds under **Input
34720 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20 69  s** are the.** i
34730 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74 49 6e  nputs to xBestIn
34740 64 65 78 20 61 6e 64 20 61 72 65 20 72 65 61 64  dex and are read
34750 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e 64  -only.  xBestInd
34760 65 78 20 69 6e 73 65 72 74 73 20 69 74 73 0a 2a  ex inserts its.*
34770 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 74  * results into t
34780 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66  he **Outputs** f
34790 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ields..**.** ^(T
347a0 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  he aConstraint[]
347b0 20 61 72 72 61 79 20 72 65 63 6f 72 64 73 20 57   array records W
347c0 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73  HERE clause cons
347d0 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65 20 66  traints of the f
347e0 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  orm:.**.** <bloc
347f0 6b 71 75 6f 74 65 3e 63 6f 6c 75 6d 6e 20 4f 50  kquote>column OP
34800 20 65 78 70 72 3c 2f 62 6c 6f 63 6b 71 75 6f 74   expr</blockquot
34810 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 4f  e>.**.** where O
34820 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c  P is =, &lt;, &l
34830 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67  t;=, &gt;, or &g
34840 74 3b 3d 2e 29 5e 20 20 5e 28 54 68 65 20 70 61  t;=.)^  ^(The pa
34850 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61 74 6f  rticular operato
34860 72 20 69 73 0a 2a 2a 20 73 74 6f 72 65 64 20 69  r is.** stored i
34870 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  n aConstraint[].
34880 6f 70 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  op using one of 
34890 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
348a0 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
348b0 45 51 20 7c 20 53 51 4c 49 54 45 5f 49 4e 44 45  EQ | SQLITE_INDE
348c0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 20 76 61  X_CONSTRAINT_ va
348d0 6c 75 65 73 5d 2e 29 5e 0a 2a 2a 20 5e 28 54 68  lues].)^.** ^(Th
348e0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
348f0 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 20  olumn is stored 
34900 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e  in.** aConstrain
34910 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 29 5e 20 20  t[].iColumn.)^  
34920 5e 28 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  ^(aConstraint[].
34930 75 73 61 62 6c 65 20 69 73 20 54 52 55 45 20 69  usable is TRUE i
34940 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e  f the.** expr on
34950 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20   the right-hand 
34960 73 69 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c  side can be eval
34970 75 61 74 65 64 20 28 61 6e 64 20 74 68 75 73 20  uated (and thus 
34980 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  the constraint.*
34990 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64  * is usable) and
349a0 20 66 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e   false if it can
349b0 6e 6f 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  not.)^.**.** ^Th
349c0 65 20 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 6f  e optimizer auto
349d0 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 74  matically invert
349e0 73 20 74 65 72 6d 73 20 6f 66 20 74 68 65 20 66  s terms of the f
349f0 6f 72 6d 20 22 65 78 70 72 20 4f 50 20 63 6f 6c  orm "expr OP col
34a00 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65  umn".** and make
34a10 73 20 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 69  s other simplifi
34a20 63 61 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 57  cations to the W
34a30 48 45 52 45 20 63 6c 61 75 73 65 20 69 6e 20 61  HERE clause in a
34a40 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20  n attempt to.** 
34a50 67 65 74 20 61 73 20 6d 61 6e 79 20 57 48 45 52  get as many WHER
34a60 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69  E clause terms i
34a70 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 6f  nto the form sho
34a80 77 6e 20 61 62 6f 76 65 20 61 73 20 70 6f 73 73  wn above as poss
34a90 69 62 6c 65 2e 0a 2a 2a 20 5e 54 68 65 20 61 43  ible..** ^The aC
34aa0 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61  onstraint[] arra
34ab0 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 57  y only reports W
34ac0 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d  HERE clause term
34ad0 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 72 65  s that are.** re
34ae0 6c 65 76 61 6e 74 20 74 6f 20 74 68 65 20 70 61  levant to the pa
34af0 72 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c  rticular virtual
34b00 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65   table being que
34b10 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 66  ried..**.** ^Inf
34b20 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
34b30 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
34b40 73 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  se is stored in 
34b50 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 5e  aOrderBy[]..** ^
34b60 45 61 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72  Each term of aOr
34b70 64 65 72 42 79 20 72 65 63 6f 72 64 73 20 61 20  derBy records a 
34b80 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52  column of the OR
34b90 44 45 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a  DER BY clause..*
34ba0 2a 0a 2a 2a 20 54 68 65 20 5b 78 42 65 73 74 49  *.** The [xBestI
34bb0 6e 64 65 78 5d 20 6d 65 74 68 6f 64 20 6d 75 73  ndex] method mus
34bc0 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69  t fill aConstrai
34bd0 6e 74 55 73 61 67 65 5b 5d 20 77 69 74 68 20 69  ntUsage[] with i
34be0 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62  nformation.** ab
34bf0 6f 75 74 20 77 68 61 74 20 70 61 72 61 6d 65 74  out what paramet
34c00 65 72 73 20 74 6f 20 70 61 73 73 20 74 6f 20 78  ers to pass to x
34c10 46 69 6c 74 65 72 2e 20 20 5e 49 66 20 61 72 67  Filter.  ^If arg
34c20 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a  vIndex>0 then.**
34c30 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20   the right-hand 
34c40 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f 72 72  side of the corr
34c50 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74  esponding aConst
34c60 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75  raint[] is evalu
34c70 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f  ated.** and beco
34c80 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e 64 65  mes the argvInde
34c90 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20 61 72  x-th entry in ar
34ca0 67 76 2e 20 20 5e 28 49 66 20 61 43 6f 6e 73 74  gv.  ^(If aConst
34cb0 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69  raintUsage[].omi
34cc0 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 68  t.** is true, th
34cd0 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  en the constrain
34ce0 74 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20  t is assumed to 
34cf0 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64  be fully handled
34d00 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 75   by the.** virtu
34d10 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73 20  al table and is 
34d20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61 69  not checked agai
34d30 6e 20 62 79 20 53 51 4c 69 74 65 2e 29 5e 0a 2a  n by SQLite.)^.*
34d40 2a 0a 2a 2a 20 5e 54 68 65 20 69 64 78 4e 75 6d  *.** ^The idxNum
34d50 20 61 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75   and idxPtr valu
34d60 65 73 20 61 72 65 20 72 65 63 6f 72 64 65 64 20  es are recorded 
34d70 61 6e 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20  and passed into 
34d80 74 68 65 0a 2a 2a 20 5b 78 46 69 6c 74 65 72 5d  the.** [xFilter]
34d90 20 6d 65 74 68 6f 64 2e 0a 2a 2a 20 5e 5b 73 71   method..** ^[sq
34da0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
34db0 20 75 73 65 64 20 74 6f 20 66 72 65 65 20 69 64   used to free id
34dc0 78 50 74 72 20 69 66 20 61 6e 64 20 6f 6e 6c 79  xPtr if and only
34dd0 20 69 66 0a 2a 2a 20 6e 65 65 64 54 6f 46 72 65   if.** needToFre
34de0 65 49 64 78 50 74 72 20 69 73 20 74 72 75 65 2e  eIdxPtr is true.
34df0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 72 64 65  .**.** ^The orde
34e00 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e  rByConsumed mean
34e10 73 20 74 68 61 74 20 6f 75 74 70 75 74 20 66 72  s that output fr
34e20 6f 6d 20 5b 78 46 69 6c 74 65 72 5d 2f 5b 78 4e  om [xFilter]/[xN
34e30 65 78 74 5d 20 77 69 6c 6c 20 6f 63 63 75 72 20  ext] will occur 
34e40 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65 63  in.** the correc
34e50 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74 69 73  t order to satis
34e60 66 79 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  fy the ORDER BY 
34e70 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74 20 6e  clause so that n
34e80 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f  o separate.** so
34e90 72 74 69 6e 67 20 73 74 65 70 20 69 73 20 72 65  rting step is re
34ea0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  quired..**.** ^T
34eb0 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74  he estimatedCost
34ec0 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73 74   value is an est
34ed0 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f 73  imate of the cos
34ee0 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a  t of doing the.*
34ef0 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f  * particular loo
34f00 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 61  kup.  A full sca
34f10 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69 74  n of a table wit
34f20 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75  h N entries shou
34f30 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73  ld have.** a cos
34f40 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 72  t of N.  A binar
34f50 79 20 73 65 61 72 63 68 20 6f 66 20 61 20 74 61  y search of a ta
34f60 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 73  ble of N entries
34f70 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a   should have a.*
34f80 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f 78  * cost of approx
34f90 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a  imately log(N)..
34fa0 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
34fb0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20  3_index_info {. 
34fc0 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20   /* Inputs */.  
34fd0 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b  int nConstraint;
34fe0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
34ff0 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20  mber of entries 
35000 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a  in aConstraint *
35010 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74  /.  struct sqlit
35020 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61  e3_index_constra
35030 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 69  int {.     int i
35040 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20  Column;         
35050 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f       /* Column o
35060 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65  n left-hand side
35070 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a   of constraint *
35080 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
35090 63 68 61 72 20 6f 70 3b 20 20 20 20 20 20 20 20  char op;        
350a0 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f   /* Constraint o
350b0 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20  perator */.     
350c0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 75 73  unsigned char us
350d0 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 75  able;     /* Tru
350e0 65 20 69 66 20 74 68 69 73 20 63 6f 6e 73 74 72  e if this constr
350f0 61 69 6e 74 20 69 73 20 75 73 61 62 6c 65 20 2a  aint is usable *
35100 2f 0a 20 20 20 20 20 69 6e 74 20 69 54 65 72 6d  /.     int iTerm
35110 4f 66 66 73 65 74 3b 20 20 20 20 20 20 20 20 20  Offset;         
35120 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61   /* Used interna
35130 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 65 78  lly - xBestIndex
35140 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a   should ignore *
35150 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69  /.  } *aConstrai
35160 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  nt;            /
35170 2a 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45  * Table of WHERE
35180 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69   clause constrai
35190 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72  nts */.  int nOr
351a0 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20  derBy;          
351b0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
351c0 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52   terms in the OR
351d0 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f  DER BY clause */
351e0 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  .  struct sqlite
351f0 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20  3_index_orderby 
35200 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75  {.     int iColu
35210 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  mn;             
35220 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65   /* Column numbe
35230 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e  r */.     unsign
35240 65 64 20 63 68 61 72 20 64 65 73 63 3b 20 20 20  ed char desc;   
35250 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20      /* True for 
35260 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72  DESC.  False for
35270 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f   ASC. */.  } *aO
35280 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20  rderBy;         
35290 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44        /* The ORD
352a0 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a  ER BY clause */.
352b0 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a    /* Outputs */.
352c0 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33    struct sqlite3
352d0 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e  _index_constrain
352e0 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69 6e  t_usage {.    in
352f0 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20 20  t argvIndex;    
35300 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c         /* if >0,
35310 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 70   constraint is p
35320 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20 78  art of argv to x
35330 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e  Filter */.    un
35340 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74  signed char omit
35350 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74  ;      /* Do not
35360 20 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72   code a test for
35370 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74   this constraint
35380 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72   */.  } *aConstr
35390 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e 74  aintUsage;.  int
353a0 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20 20 20   idxNum;        
353b0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
353c0 72 20 75 73 65 64 20 74 6f 20 69 64 65 6e 74 69  r used to identi
353d0 66 79 20 74 68 65 20 69 6e 64 65 78 20 2a 2f 0a  fy the index */.
353e0 20 20 63 68 61 72 20 2a 69 64 78 53 74 72 3b 20    char *idxStr; 
353f0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
35400 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c 79  String, possibly
35410 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
35420 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f  qlite3_malloc */
35430 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72 65  .  int needToFre
35440 65 49 64 78 53 74 72 3b 20 20 20 20 20 20 2f 2a  eIdxStr;      /*
35450 20 46 72 65 65 20 69 64 78 53 74 72 20 75 73 69   Free idxStr usi
35460 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
35470 29 20 69 66 20 74 72 75 65 20 2a 2f 0a 20 20 69  ) if true */.  i
35480 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d  nt orderByConsum
35490 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75  ed;       /* Tru
354a0 65 20 69 66 20 6f 75 74 70 75 74 20 69 73 20 61  e if output is a
354b0 6c 72 65 61 64 79 20 6f 72 64 65 72 65 64 20 2a  lready ordered *
354c0 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 74 69 6d  /.  double estim
354d0 61 74 65 64 43 6f 73 74 3b 20 20 20 20 20 20 2f  atedCost;      /
354e0 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73 74  * Estimated cost
354f0 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20 69   of using this i
35500 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ndex */.};../*.*
35510 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
35520 75 61 6c 20 54 61 62 6c 65 20 43 6f 6e 73 74 72  ual Table Constr
35530 61 69 6e 74 20 4f 70 65 72 61 74 6f 72 20 43 6f  aint Operator Co
35540 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  des.**.** These 
35550 6d 61 63 72 6f 73 20 64 65 66 69 6e 65 64 20 74  macros defined t
35560 68 65 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65  he allowed value
35570 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 73 71  s for the.** [sq
35580 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
35590 5d 2e 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  ].aConstraint[].
355a0 6f 70 20 66 69 65 6c 64 2e 20 20 45 61 63 68 20  op field.  Each 
355b0 76 61 6c 75 65 20 72 65 70 72 65 73 65 6e 74 73  value represents
355c0 0a 2a 2a 20 61 6e 20 6f 70 65 72 61 74 6f 72 20  .** an operator 
355d0 74 68 61 74 20 69 73 20 70 61 72 74 20 6f 66 20  that is part of 
355e0 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 74 65 72  a constraint ter
355f0 6d 20 69 6e 20 74 68 65 20 77 48 45 52 45 20 63  m in the wHERE c
35600 6c 61 75 73 65 20 6f 66 0a 2a 2a 20 61 20 71 75  lause of.** a qu
35610 65 72 79 20 74 68 61 74 20 75 73 65 73 20 61 20  ery that uses a 
35620 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e  [virtual table].
35630 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
35640 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
35650 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66  INT_EQ    2.#def
35660 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
35670 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20  _CONSTRAINT_GT  
35680 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
35690 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
356a0 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66  INT_LE    8.#def
356b0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
356c0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20  _CONSTRAINT_LT  
356d0 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c    16.#define SQL
356e0 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
356f0 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64  AINT_GE    32.#d
35700 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
35710 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41  EX_CONSTRAINT_MA
35720 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41  TCH 64../*.** CA
35730 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
35740 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
35750 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   Implementation.
35760 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
35770 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74  tines are used t
35780 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e 65 77  o register a new
35790 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
357a0 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a  module] name..**
357b0 20 5e 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d   ^Module names m
357c0 75 73 74 20 62 65 20 72 65 67 69 73 74 65 72 65  ust be registere
357d0 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61  d before.** crea
357e0 74 69 6e 67 20 61 20 6e 65 77 20 5b 76 69 72 74  ting a new [virt
357f0 75 61 6c 20 74 61 62 6c 65 5d 20 75 73 69 6e 67  ual table] using
35800 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20   the module and 
35810 62 65 66 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a  before using a.*
35820 2a 20 70 72 65 65 78 69 73 74 69 6e 67 20 5b 76  * preexisting [v
35830 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f  irtual table] fo
35840 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a  r the module..**
35850 0a 2a 2a 20 5e 54 68 65 20 6d 6f 64 75 6c 65 20  .** ^The module 
35860 6e 61 6d 65 20 69 73 20 72 65 67 69 73 74 65 72  name is register
35870 65 64 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ed on the [datab
35880 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
35890 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
358a0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
358b0 74 65 72 2e 20 20 5e 54 68 65 20 6e 61 6d 65 20  ter.  ^The name 
358c0 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 73  of the module is
358d0 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 0a 2a   given by the .*
358e0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
358f0 65 72 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  er.  ^The third 
35900 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
35910 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ointer to.** the
35920 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35930 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20  of the [virtual 
35940 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20  table module].  
35950 20 5e 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20   ^The fourth.** 
35960 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
35970 61 72 62 69 74 72 61 72 79 20 63 6c 69 65 6e 74  arbitrary client
35980 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68   data pointer th
35990 61 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72  at is passed thr
359a0 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  ough.** into the
359b0 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b   [xCreate] and [
359c0 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64  xConnect] method
359d0 73 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c  s of the virtual
359e0 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a 2a   table module.**
359f0 20 77 68 65 6e 20 61 20 6e 65 77 20 76 69 72 74   when a new virt
35a00 75 61 6c 20 74 61 62 6c 65 20 69 73 20 62 65 20  ual table is be 
35a10 62 65 69 6e 67 20 63 72 65 61 74 65 64 20 6f 72  being created or
35a20 20 72 65 69 6e 69 74 69 61 6c 69 7a 65 64 2e 0a   reinitialized..
35a30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
35a40 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
35a50 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
35a60 68 61 73 20 61 20 66 69 66 74 68 20 70 61 72 61  has a fifth para
35a70 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  meter which.** i
35a80 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
35a90 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
35aa0 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74 61 2e  the pClientData.
35ab0 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a    ^SQLite will.*
35ac0 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  * invoke the des
35ad0 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
35ae0 20 28 69 66 20 69 74 20 69 73 20 6e 6f 74 20 4e   (if it is not N
35af0 55 4c 4c 29 20 77 68 65 6e 20 53 51 4c 69 74 65  ULL) when SQLite
35b00 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65  .** no longer ne
35b10 65 64 73 20 74 68 65 20 70 43 6c 69 65 6e 74 44  eds the pClientD
35b20 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ata pointer.  ^T
35b30 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69  he destructor wi
35b40 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 69 6e  ll also.** be in
35b50 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c  voked if the cal
35b60 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  l to sqlite3_cre
35b70 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20  ate_module_v2() 
35b80 66 61 69 6c 73 2e 0a 2a 2a 20 5e 54 68 65 20 73  fails..** ^The s
35b90 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
35ba0 64 75 6c 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  dule().** interf
35bb0 61 63 65 20 69 73 20 65 71 75 69 76 61 6c 65 6e  ace is equivalen
35bc0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  t to sqlite3_cre
35bd0 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20  ate_module_v2() 
35be0 77 69 74 68 20 61 20 4e 55 4c 4c 0a 2a 2a 20 64  with a NULL.** d
35bf0 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a 69 6e  estructor..*/.in
35c00 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
35c10 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74  _module(.  sqlit
35c20 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
35c30 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20        /* SQLite 
35c40 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65  connection to re
35c50 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69  gister module wi
35c60 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  th */.  const ch
35c70 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20  ar *zName,      
35c80 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
35c90 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f  e module */.  co
35ca0 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  nst sqlite3_modu
35cb0 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68  le *p,   /* Meth
35cc0 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75  ods for the modu
35cd0 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43  le */.  void *pC
35ce0 6c 69 65 6e 74 44 61 74 61 20 20 20 20 20 20 20  lientData       
35cf0 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74     /* Client dat
35d00 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43  a for xCreate/xC
35d10 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 69 6e 74  onnect */.);.int
35d20 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
35d30 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c  module_v2(.  sql
35d40 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
35d50 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74          /* SQLit
35d60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
35d70 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20  register module 
35d80 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  with */.  const 
35d90 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20  char *zName,    
35da0 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
35db0 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
35dc0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f  const sqlite3_mo
35dd0 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65  dule *p,   /* Me
35de0 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f  thods for the mo
35df0 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  dule */.  void *
35e00 70 43 6c 69 65 6e 74 44 61 74 61 2c 20 20 20 20  pClientData,    
35e10 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64       /* Client d
35e20 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f  ata for xCreate/
35e30 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f  xConnect */.  vo
35e40 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
35e50 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75  id*)     /* Modu
35e60 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75  le destructor fu
35e70 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a  nction */.);../*
35e80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69  .** CAPI3REF: Vi
35e90 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 73 74  rtual Table Inst
35ea0 61 6e 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  ance Object.** K
35eb0 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
35ec0 5f 76 74 61 62 0a 2a 2a 0a 2a 2a 20 45 76 65 72  _vtab.**.** Ever
35ed0 79 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  y [virtual table
35ee0 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65   module] impleme
35ef0 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73  ntation uses a s
35f00 75 62 63 6c 61 73 73 0a 2a 2a 20 6f 66 20 74 68  ubclass.** of th
35f10 69 73 20 6f 62 6a 65 63 74 20 74 6f 20 64 65 73  is object to des
35f20 63 72 69 62 65 20 61 20 70 61 72 74 69 63 75 6c  cribe a particul
35f30 61 72 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 6f  ar instance.** o
35f40 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74  f the [virtual t
35f50 61 62 6c 65 5d 2e 20 20 45 61 63 68 20 73 75 62  able].  Each sub
35f60 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65  class will.** be
35f70 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68 65   tailored to the
35f80 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
35f90 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d  of the module im
35fa0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a  plementation..**
35fb0 20 54 68 65 20 70 75 72 70 6f 73 65 20 6f 66 20   The purpose of 
35fc0 74 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20  this superclass 
35fd0 69 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65 72  is to define cer
35fe0 74 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61 74  tain fields that
35ff0 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74   are.** common t
36000 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70  o all module imp
36010 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a  lementations..**
36020 0a 2a 2a 20 5e 56 69 72 74 75 61 6c 20 74 61 62  .** ^Virtual tab
36030 6c 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20  les methods can 
36040 73 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  set an error mes
36050 73 61 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e  sage by assignin
36060 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62  g a.** string ob
36070 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
36080 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20  ite3_mprintf()] 
36090 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65  to zErrMsg.  The
360a0 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a   method should.*
360b0 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68 61 74  * take care that
360c0 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e   any prior strin
360d0 67 20 69 73 20 66 72 65 65 64 20 62 79 20 61 20  g is freed by a 
360e0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
360f0 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69 6f  _free()].** prio
36100 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61  r to assigning a
36110 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a   new string to z
36120 45 72 72 4d 73 67 2e 20 20 5e 41 66 74 65 72 20  ErrMsg.  ^After 
36130 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
36140 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65  e.** is delivere
36150 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65  d up to the clie
36160 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  nt application, 
36170 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
36180 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
36190 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c  .** freed by sql
361a0 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20  ite3_free() and 
361b0 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c  the zErrMsg fiel
361c0 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64  d will be zeroed
361d0 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
361e0 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e  te3_vtab {.  con
361f0 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  st sqlite3_modul
36200 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20  e *pModule;  /* 
36210 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74  The module for t
36220 68 69 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c  his virtual tabl
36230 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b  e */.  int nRef;
36240 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36250 20 20 20 20 20 20 20 2f 2a 20 4e 4f 20 4c 4f 4e         /* NO LON
36260 47 45 52 20 55 53 45 44 20 2a 2f 0a 20 20 63 68  GER USED */.  ch
36270 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20  ar *zErrMsg;    
36280 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
36290 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66   Error message f
362a0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  rom sqlite3_mpri
362b0 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69  ntf() */.  /* Vi
362c0 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
362d0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
362e0 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61   typically add a
362f0 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
36300 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
36310 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
36320 54 61 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a  Table Cursor Obj
36330 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
36340 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
36350 72 73 6f 72 20 7b 76 69 72 74 75 61 6c 20 74 61  rsor {virtual ta
36360 62 6c 65 20 63 75 72 73 6f 72 7d 0a 2a 2a 0a 2a  ble cursor}.**.*
36370 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c  * Every [virtual
36380 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69   table module] i
36390 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73  mplementation us
363a0 65 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66  es a subclass of
363b0 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   the.** followin
363c0 67 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 64  g structure to d
363d0 65 73 63 72 69 62 65 20 63 75 72 73 6f 72 73 20  escribe cursors 
363e0 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f 20  that point into 
363f0 74 68 65 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20  the.** [virtual 
36400 74 61 62 6c 65 5d 20 61 6e 64 20 61 72 65 20 75  table] and are u
36410 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74  sed.** to loop t
36420 68 72 6f 75 67 68 20 74 68 65 20 76 69 72 74 75  hrough the virtu
36430 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73 6f  al table.  Curso
36440 72 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  rs are created u
36450 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
36460 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f 70 65  ite3_module.xOpe
36470 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  n | xOpen] metho
36480 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20  d of the module 
36490 61 6e 64 20 61 72 65 20 64 65 73 74 72 6f 79 65  and are destroye
364a0 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 73 71 6c  d.** by the [sql
364b0 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 43 6c 6f  ite3_module.xClo
364c0 73 65 20 7c 20 78 43 6c 6f 73 65 5d 20 6d 65 74  se | xClose] met
364d0 68 6f 64 2e 20 20 43 75 72 73 6f 72 73 20 61 72  hod.  Cursors ar
364e0 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65  e used.** by the
364f0 20 5b 78 46 69 6c 74 65 72 5d 2c 20 5b 78 4e 65   [xFilter], [xNe
36500 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b 78 43  xt], [xEof], [xC
36510 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78 52 6f  olumn], and [xRo
36520 77 69 64 5d 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  wid] methods.** 
36530 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20  of the module.  
36540 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c  Each module impl
36550 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20  ementation will 
36560 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f  define.** the co
36570 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f  ntent of a curso
36580 72 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 73  r structure to s
36590 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64  uit its own need
365a0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75  s..**.** This su
365b0 70 65 72 63 6c 61 73 73 20 65 78 69 73 74 73 20  perclass exists 
365c0 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69  in order to defi
365d0 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65  ne fields of the
365e0 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20   cursor that.** 
365f0 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c  are common to al
36600 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  l implementation
36610 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  s..*/.struct sql
36620 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
36630 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 61   {.  sqlite3_vta
36640 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20 2f  b *pVtab;      /
36650 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * Virtual table 
36660 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72 20 2a  of this cursor *
36670 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74  /.  /* Virtual t
36680 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
36690 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61  ions will typica
366a0 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e  lly add addition
366b0 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a  al fields */.};.
366c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
366d0 20 44 65 63 6c 61 72 65 20 54 68 65 20 53 63 68   Declare The Sch
366e0 65 6d 61 20 4f 66 20 41 20 56 69 72 74 75 61 6c  ema Of A Virtual
366f0 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68   Table.**.** ^Th
36700 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20  e [xCreate] and 
36710 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f  [xConnect] metho
36720 64 73 20 6f 66 20 61 0a 2a 2a 20 5b 76 69 72 74  ds of a.** [virt
36730 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
36740 5d 20 63 61 6c 6c 20 74 68 69 73 20 69 6e 74 65  ] call this inte
36750 72 66 61 63 65 0a 2a 2a 20 74 6f 20 64 65 63 6c  rface.** to decl
36760 61 72 65 20 74 68 65 20 66 6f 72 6d 61 74 20 28  are the format (
36770 74 68 65 20 6e 61 6d 65 73 20 61 6e 64 20 64 61  the names and da
36780 74 61 74 79 70 65 73 20 6f 66 20 74 68 65 20 63  tatypes of the c
36790 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68  olumns) of.** th
367a0 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  e virtual tables
367b0 20 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e   they implement.
367c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
367d0 64 65 63 6c 61 72 65 5f 76 74 61 62 28 73 71 6c  declare_vtab(sql
367e0 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61  ite3*, const cha
367f0 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a 2a 2a  r *zSQL);../*.**
36800 20 43 41 50 49 33 52 45 46 3a 20 4f 76 65 72 6c   CAPI3REF: Overl
36810 6f 61 64 20 41 20 46 75 6e 63 74 69 6f 6e 20 46  oad A Function F
36820 6f 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62  or A Virtual Tab
36830 6c 65 0a 2a 2a 0a 2a 2a 20 5e 28 56 69 72 74 75  le.**.** ^(Virtu
36840 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 70 72  al tables can pr
36850 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74 69 76  ovide alternativ
36860 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
36870 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  s of functions.*
36880 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 78 46 69  * using the [xFi
36890 6e 64 46 75 6e 63 74 69 6f 6e 5d 20 6d 65 74 68  ndFunction] meth
368a0 6f 64 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75  od of the [virtu
368b0 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
368c0 2e 20 20 0a 2a 2a 20 42 75 74 20 67 6c 6f 62 61  .  .** But globa
368d0 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68  l versions of th
368e0 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ose functions.**
368f0 20 6d 75 73 74 20 65 78 69 73 74 20 69 6e 20 6f   must exist in o
36900 72 64 65 72 20 74 6f 20 62 65 20 6f 76 65 72 6c  rder to be overl
36910 6f 61 64 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  oaded.)^.**.** ^
36920 28 54 68 69 73 20 41 50 49 20 6d 61 6b 65 73 20  (This API makes 
36930 73 75 72 65 20 61 20 67 6c 6f 62 61 6c 20 76 65  sure a global ve
36940 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e 63 74  rsion of a funct
36950 69 6f 6e 20 77 69 74 68 20 61 20 70 61 72 74 69  ion with a parti
36960 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e  cular.** name an
36970 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61  d number of para
36980 6d 65 74 65 72 73 20 65 78 69 73 74 73 2e 20 20  meters exists.  
36990 49 66 20 6e 6f 20 73 75 63 68 20 66 75 6e 63 74  If no such funct
369a0 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20 62 65  ion exists.** be
369b0 66 6f 72 65 20 74 68 69 73 20 41 50 49 20 69 73  fore this API is
369c0 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77 20 66   called, a new f
369d0 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74  unction is creat
369e0 65 64 2e 29 5e 20 20 5e 54 68 65 20 69 6d 70 6c  ed.)^  ^The impl
369f0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66  ementation.** of
36a00 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f   the new functio
36a10 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 73 20  n always causes 
36a20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20  an exception to 
36a30 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a  be thrown.  So.*
36a40 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69  * the new functi
36a50 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66  on is not good f
36a60 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20 69  or anything by i
36a70 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79  tself.  Its only
36a80 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20 74  .** purpose is t
36a90 6f 20 62 65 20 61 20 70 6c 61 63 65 68 6f 6c 64  o be a placehold
36aa0 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  er function that
36ab0 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64   can be overload
36ac0 65 64 0a 2a 2a 20 62 79 20 61 20 5b 76 69 72 74  ed.** by a [virt
36ad0 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 69  ual table]..*/.i
36ae0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c  nt sqlite3_overl
36af0 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c  oad_function(sql
36b00 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61  ite3*, const cha
36b10 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e  r *zFuncName, in
36b20 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t nArg);../*.** 
36b30 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f  The interface to
36b40 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
36b50 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 66  le mechanism def
36b60 69 6e 65 64 20 61 62 6f 76 65 20 28 62 61 63 6b  ined above (back
36b70 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d   up.** to a comm
36b80 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 73  ent remarkably s
36b90 69 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 20 6f  imilar to this o
36ba0 6e 65 29 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ne) is currently
36bb0 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74   considered.** t
36bc0 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61  o be experimenta
36bd0 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63  l.  The interfac
36be0 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  e might change i
36bf0 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77  n incompatible w
36c00 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  ays..** If this 
36c10 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72  is a problem for
36c20 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65   you, do not use
36c30 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 61   the interface a
36c40 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a  t this time..**.
36c50 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 74  ** When the virt
36c60 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e  ual-table mechan
36c70 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20  ism stabilizes, 
36c80 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20  we will declare 
36c90 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  the.** interface
36ca0 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20   fixed, support 
36cb0 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c  it indefinitely,
36cc0 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73   and remove this
36cd0 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a   comment..*/../*
36ce0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 20  .** CAPI3REF: A 
36cf0 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65  Handle To An Ope
36d00 6e 20 42 4c 4f 42 0a 2a 2a 20 4b 45 59 57 4f 52  n BLOB.** KEYWOR
36d10 44 53 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65  DS: {BLOB handle
36d20 7d 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 7d  } {BLOB handles}
36d30 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
36d40 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
36d50 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
36d60 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 69  open BLOB on whi
36d70 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ch.** [sqlite3_b
36d80 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
36d90 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d  mental BLOB I/O]
36da0 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
36db0 64 2e 0a 2a 2a 20 5e 4f 62 6a 65 63 74 73 20 6f  d..** ^Objects o
36dc0 66 20 74 68 69 73 20 74 79 70 65 20 61 72 65 20  f this type are 
36dd0 63 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69  created by [sqli
36de0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
36df0 0a 2a 2a 20 61 6e 64 20 64 65 73 74 72 6f 79 65  .** and destroye
36e00 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c  d by [sqlite3_bl
36e10 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20  ob_close()]..** 
36e20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c  ^The [sqlite3_bl
36e30 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b  ob_read()] and [
36e40 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69  sqlite3_blob_wri
36e50 74 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  te()] interfaces
36e60 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20  .** can be used 
36e70 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  to read or write
36e80 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 74 69 6f   small subsectio
36e90 6e 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 0a  ns of the BLOB..
36ea0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
36eb0 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69  _blob_bytes()] i
36ec0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
36ed0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
36ee0 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 0a   BLOB in bytes..
36ef0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
36f00 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73  t sqlite3_blob s
36f10 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a  qlite3_blob;../*
36f20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
36f30 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e  en A BLOB For In
36f40 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 0a 2a 2a  cremental I/O.**
36f50 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
36f60 66 61 63 65 73 20 6f 70 65 6e 73 20 61 20 5b 42  faces opens a [B
36f70 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20 68 61 6e  LOB handle | han
36f80 64 6c 65 5d 20 74 6f 20 74 68 65 20 42 4c 4f 42  dle] to the BLOB
36f90 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72   located.** in r
36fa0 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20  ow iRow, column 
36fb0 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 7a  zColumn, table z
36fc0 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62 61 73  Table in databas
36fd0 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68  e zDb;.** in oth
36fe0 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 73 61  er words, the sa
36ff0 6d 65 20 42 4c 4f 42 20 74 68 61 74 20 77 6f 75  me BLOB that wou
37000 6c 64 20 62 65 20 73 65 6c 65 63 74 65 64 20 62  ld be selected b
37010 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a  y:.**.** <pre>.*
37020 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f  *     SELECT zCo
37030 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54  lumn FROM zDb.zT
37040 61 62 6c 65 20 57 48 45 52 45 20 5b 72 6f 77 69  able WHERE [rowi
37050 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f  d] = iRow;.** </
37060 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66  pre>)^.**.** ^If
37070 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d   the flags param
37080 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f  eter is non-zero
37090 2c 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20  , then the BLOB 
370a0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
370b0 61 64 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65 20  ad.** and write 
370c0 61 63 63 65 73 73 2e 20 5e 49 66 20 69 74 20 69  access. ^If it i
370d0 73 20 7a 65 72 6f 2c 20 74 68 65 20 42 4c 4f 42  s zero, the BLOB
370e0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
370f0 65 61 64 20 61 63 63 65 73 73 2e 0a 2a 2a 20 5e  ead access..** ^
37100 49 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  It is not possib
37110 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c  le to open a col
37120 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61 72 74  umn that is part
37130 20 6f 66 20 61 6e 20 69 6e 64 65 78 20 6f 72 20   of an index or 
37140 70 72 69 6d 61 72 79 20 0a 2a 2a 20 6b 65 79 20  primary .** key 
37150 66 6f 72 20 77 72 69 74 69 6e 67 2e 20 5e 49 66  for writing. ^If
37160 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f   [foreign key co
37170 6e 73 74 72 61 69 6e 74 73 5d 20 61 72 65 20 65  nstraints] are e
37180 6e 61 62 6c 65 64 2c 20 69 74 20 69 73 20 0a 2a  nabled, it is .*
37190 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  * not possible t
371a0 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20  o open a column 
371b0 74 68 61 74 20 69 73 20 70 61 72 74 20 6f 66 20  that is part of 
371c0 61 20 5b 63 68 69 6c 64 20 6b 65 79 5d 20 66 6f  a [child key] fo
371d0 72 20 77 72 69 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  r writing..**.**
371e0 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
371f0 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73  database name is
37200 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 6e 61 6d   not the filenam
37210 65 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 0a  e that contains.
37220 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
37230 62 75 74 20 72 61 74 68 65 72 20 74 68 65 20 73  but rather the s
37240 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 20  ymbolic name of 
37250 74 68 65 20 64 61 74 61 62 61 73 65 20 74 68 61  the database tha
37260 74 0a 2a 2a 20 61 70 70 65 61 72 73 20 61 66 74  t.** appears aft
37270 65 72 20 74 68 65 20 41 53 20 6b 65 79 77 6f 72  er the AS keywor
37280 64 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  d when the datab
37290 61 73 65 20 69 73 20 63 6f 6e 6e 65 63 74 65 64  ase is connected
372a0 20 75 73 69 6e 67 20 5b 41 54 54 41 43 48 5d 2e   using [ATTACH].
372b0 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 6d 61 69  .** ^For the mai
372c0 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  n database file,
372d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
372e0 6d 65 20 69 73 20 22 6d 61 69 6e 22 2e 0a 2a 2a  me is "main"..**
372f0 20 5e 46 6f 72 20 54 45 4d 50 20 74 61 62 6c 65   ^For TEMP table
37300 73 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20  s, the database 
37310 6e 61 6d 65 20 69 73 20 22 74 65 6d 70 22 2e 0a  name is "temp"..
37320 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 65  **.** ^(On succe
37330 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  ss, [SQLITE_OK] 
37340 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
37350 74 68 65 20 6e 65 77 20 5b 42 4c 4f 42 20 68 61  the new [BLOB ha
37360 6e 64 6c 65 5d 20 69 73 20 77 72 69 74 74 65 6e  ndle] is written
37370 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 20  .** to *ppBlob. 
37380 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  Otherwise an [er
37390 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
373a0 75 72 6e 65 64 20 61 6e 64 20 2a 70 70 42 6c 6f  urned and *ppBlo
373b0 62 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 62  b is set.** to b
373c0 65 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 65 72  e a null pointer
373d0 2e 29 5e 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .)^.** ^This fun
373e0 63 74 69 6f 6e 20 73 65 74 73 20 74 68 65 20 5b  ction sets the [
373f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37400 69 6f 6e 5d 20 65 72 72 6f 72 20 63 6f 64 65 20  ion] error code 
37410 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61  and message.** a
37420 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73  ccessible via [s
37430 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
37440 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  ] and [sqlite3_e
37450 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 72 65 6c  rrmsg()] and rel
37460 61 74 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ated.** function
37470 73 2e 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  s. ^Note that th
37480 65 20 2a 70 70 42 6c 6f 62 20 76 61 72 69 61 62  e *ppBlob variab
37490 6c 65 20 69 73 20 61 6c 77 61 79 73 20 69 6e 69  le is always ini
374a0 74 69 61 6c 69 7a 65 64 20 69 6e 20 61 0a 2a 2a  tialized in a.**
374b0 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20   way that makes 
374c0 69 74 20 73 61 66 65 20 74 6f 20 69 6e 76 6f 6b  it safe to invok
374d0 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
374e0 63 6c 6f 73 65 28 29 5d 20 6f 6e 20 2a 70 70 42  close()] on *ppB
374f0 6c 6f 62 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  lob.** regardles
37500 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73  s of the success
37510 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74   or failure of t
37520 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a  his routine..**.
37530 2a 2a 20 5e 28 49 66 20 74 68 65 20 72 6f 77 20  ** ^(If the row 
37540 74 68 61 74 20 61 20 42 4c 4f 42 20 68 61 6e 64  that a BLOB hand
37550 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20  le points to is 
37560 6d 6f 64 69 66 69 65 64 20 62 79 20 61 6e 0a 2a  modified by an.*
37570 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44 45 4c  * [UPDATE], [DEL
37580 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b 4f 4e 20  ETE], or by [ON 
37590 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65 2d 65  CONFLICT] side-e
375a0 66 66 65 63 74 73 0a 2a 2a 20 74 68 65 6e 20 74  ffects.** then t
375b0 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69  he BLOB handle i
375c0 73 20 6d 61 72 6b 65 64 20 61 73 20 22 65 78 70  s marked as "exp
375d0 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69 73 20 69  ired"..** This i
375e0 73 20 74 72 75 65 20 69 66 20 61 6e 79 20 63 6f  s true if any co
375f0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 6f 77 20  lumn of the row 
37600 69 73 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e  is changed, even
37610 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74 68   a column.** oth
37620 65 72 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  er than the one 
37630 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20  the BLOB handle 
37640 69 73 20 6f 70 65 6e 20 6f 6e 2e 29 5e 0a 2a 2a  is open on.)^.**
37650 20 5e 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69   ^Calls to [sqli
37660 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d  te3_blob_read()]
37670 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c   and [sqlite3_bl
37680 6f 62 5f 77 72 69 74 65 28 29 5d 20 66 6f 72 0a  ob_write()] for.
37690 2a 2a 20 61 20 65 78 70 69 72 65 64 20 42 4c 4f  ** a expired BLO
376a0 42 20 68 61 6e 64 6c 65 20 66 61 69 6c 20 77 69  B handle fail wi
376b0 74 68 20 61 6e 20 72 65 74 75 72 6e 20 63 6f 64  th an return cod
376c0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f  e of [SQLITE_ABO
376d0 52 54 5d 2e 0a 2a 2a 20 5e 28 43 68 61 6e 67 65  RT]..** ^(Change
376e0 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 61  s written into a
376f0 20 42 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20 74   BLOB prior to t
37700 68 65 20 42 4c 4f 42 20 65 78 70 69 72 69 6e 67  he BLOB expiring
37710 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c   are not.** roll
37720 65 64 20 62 61 63 6b 20 62 79 20 74 68 65 20 65  ed back by the e
37730 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  xpiration of the
37740 20 42 4c 4f 42 2e 20 20 53 75 63 68 20 63 68 61   BLOB.  Such cha
37750 6e 67 65 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  nges will eventu
37760 61 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69  ally.** commit i
37770 66 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  f the transactio
37780 6e 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  n continues to c
37790 6f 6d 70 6c 65 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a  ompletion.)^.**.
377a0 2a 2a 20 5e 55 73 65 20 74 68 65 20 5b 73 71 6c  ** ^Use the [sql
377b0 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
377c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  )] interface to 
377d0 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 73 69  determine the si
377e0 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 65  ze of.** the ope
377f0 6e 65 64 20 62 6c 6f 62 2e 20 20 5e 54 68 65 20  ned blob.  ^The 
37800 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 20 6d  size of a blob m
37810 61 79 20 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  ay not be change
37820 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 69 6e 74  d by this.** int
37830 65 72 66 61 63 65 2e 20 20 55 73 65 20 74 68 65  erface.  Use the
37840 20 5b 55 50 44 41 54 45 5d 20 53 51 4c 20 63 6f   [UPDATE] SQL co
37850 6d 6d 61 6e 64 20 74 6f 20 63 68 61 6e 67 65 20  mmand to change 
37860 74 68 65 20 73 69 7a 65 20 6f 66 20 61 0a 2a 2a  the size of a.**
37870 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   blob..**.** ^Th
37880 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
37890 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 61 6e 64 20  zeroblob()] and 
378a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
378b0 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 69 6e 74 65  zeroblob()] inte
378c0 72 66 61 63 65 73 0a 2a 2a 20 61 6e 64 20 74 68  rfaces.** and th
378d0 65 20 62 75 69 6c 74 2d 69 6e 20 5b 7a 65 72 6f  e built-in [zero
378e0 62 6c 6f 62 5d 20 53 51 4c 20 66 75 6e 63 74 69  blob] SQL functi
378f0 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20  on can be used, 
37900 69 66 20 64 65 73 69 72 65 64 2c 0a 2a 2a 20 74  if desired,.** t
37910 6f 20 63 72 65 61 74 65 20 61 6e 20 65 6d 70 74  o create an empt
37920 79 2c 20 7a 65 72 6f 2d 66 69 6c 6c 65 64 20 62  y, zero-filled b
37930 6c 6f 62 20 69 6e 20 77 68 69 63 68 20 74 6f 20  lob in which to 
37940 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 75 73  read or write us
37950 69 6e 67 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65  ing.** this inte
37960 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20  rface..**.** To 
37970 61 76 6f 69 64 20 61 20 72 65 73 6f 75 72 63 65  avoid a resource
37980 20 6c 65 61 6b 2c 20 65 76 65 72 79 20 6f 70 65   leak, every ope
37990 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  n [BLOB handle] 
379a0 73 68 6f 75 6c 64 20 65 76 65 6e 74 75 61 6c 6c  should eventuall
379b0 79 0a 2a 2a 20 62 65 20 72 65 6c 65 61 73 65 64  y.** be released
379c0 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73   by a call to [s
379d0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
379e0 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  e()]..*/.int sql
379f0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a  ite3_blob_open(.
37a00 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f    sqlite3*,.  co
37a10 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20  nst char *zDb,. 
37a20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61   const char *zTa
37a30 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  ble,.  const cha
37a40 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71  r *zColumn,.  sq
37a50 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 52 6f 77  lite3_int64 iRow
37a60 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20  ,.  int flags,. 
37a70 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a   sqlite3_blob **
37a80 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ppBlob.);../*.**
37a90 20 43 41 50 49 33 52 45 46 3a 20 4d 6f 76 65 20   CAPI3REF: Move 
37aa0 61 20 42 4c 4f 42 20 48 61 6e 64 6c 65 20 74 6f  a BLOB Handle to
37ab0 20 61 20 4e 65 77 20 52 6f 77 0a 2a 2a 0a 2a 2a   a New Row.**.**
37ac0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
37ad0 69 73 20 75 73 65 64 20 74 6f 20 6d 6f 76 65 20  is used to move 
37ae0 61 6e 20 65 78 69 73 74 69 6e 67 20 62 6c 6f 62  an existing blob
37af0 20 68 61 6e 64 6c 65 20 73 6f 20 74 68 61 74 20   handle so that 
37b00 69 74 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20  it points.** to 
37b10 61 20 64 69 66 66 65 72 65 6e 74 20 72 6f 77 20  a different row 
37b20 6f 66 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  of the same data
37b30 62 61 73 65 20 74 61 62 6c 65 2e 20 5e 54 68 65  base table. ^The
37b40 20 6e 65 77 20 72 6f 77 20 69 73 20 69 64 65 6e   new row is iden
37b50 74 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  tified.** by the
37b60 20 72 6f 77 69 64 20 76 61 6c 75 65 20 70 61 73   rowid value pas
37b70 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
37b80 64 20 61 72 67 75 6d 65 6e 74 2e 20 4f 6e 6c 79  d argument. Only
37b90 20 74 68 65 20 72 6f 77 20 63 61 6e 20 62 65 0a   the row can be.
37ba0 2a 2a 20 63 68 61 6e 67 65 64 2e 20 5e 54 68 65  ** changed. ^The
37bb0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
37bc0 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6f 6e 20 77   and column on w
37bd0 68 69 63 68 20 74 68 65 20 62 6c 6f 62 20 68 61  hich the blob ha
37be0 6e 64 6c 65 20 69 73 20 6f 70 65 6e 0a 2a 2a 20  ndle is open.** 
37bf0 72 65 6d 61 69 6e 20 74 68 65 20 73 61 6d 65 2e  remain the same.
37c00 20 4d 6f 76 69 6e 67 20 61 6e 20 65 78 69 73 74   Moving an exist
37c10 69 6e 67 20 62 6c 6f 62 20 68 61 6e 64 6c 65 20  ing blob handle 
37c20 74 6f 20 61 20 6e 65 77 20 72 6f 77 20 63 61 6e  to a new row can
37c30 20 62 65 0a 2a 2a 20 66 61 73 74 65 72 20 74 68   be.** faster th
37c40 61 6e 20 63 6c 6f 73 69 6e 67 20 74 68 65 20 65  an closing the e
37c50 78 69 73 74 69 6e 67 20 68 61 6e 64 6c 65 20 61  xisting handle a
37c60 6e 64 20 6f 70 65 6e 69 6e 67 20 61 20 6e 65 77  nd opening a new
37c70 20 6f 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68   one..**.** ^(Th
37c80 65 20 6e 65 77 20 72 6f 77 20 6d 75 73 74 20 6d  e new row must m
37c90 65 65 74 20 74 68 65 20 73 61 6d 65 20 63 72 69  eet the same cri
37ca0 74 65 72 69 61 20 61 73 20 66 6f 72 20 5b 73 71  teria as for [sq
37cb0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
37cc0 29 5d 20 2d 0a 2a 2a 20 69 74 20 6d 75 73 74 20  )] -.** it must 
37cd0 65 78 69 73 74 20 61 6e 64 20 74 68 65 72 65 20  exist and there 
37ce0 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
37cf0 20 62 6c 6f 62 20 6f 72 20 74 65 78 74 20 76 61   blob or text va
37d00 6c 75 65 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a  lue stored in.**
37d10 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 63   the nominated c
37d20 6f 6c 75 6d 6e 2e 29 5e 20 5e 49 66 20 74 68 65  olumn.)^ ^If the
37d30 20 6e 65 77 20 72 6f 77 20 69 73 20 6e 6f 74 20   new row is not 
37d40 70 72 65 73 65 6e 74 20 69 6e 20 74 68 65 20 74  present in the t
37d50 61 62 6c 65 2c 20 6f 72 20 69 66 0a 2a 2a 20 69  able, or if.** i
37d60 74 20 64 6f 65 73 20 6e 6f 74 20 63 6f 6e 74 61  t does not conta
37d70 69 6e 20 61 20 62 6c 6f 62 20 6f 72 20 74 65 78  in a blob or tex
37d80 74 20 76 61 6c 75 65 2c 20 6f 72 20 69 66 20 61  t value, or if a
37d90 6e 6f 74 68 65 72 20 65 72 72 6f 72 20 6f 63 63  nother error occ
37da0 75 72 73 2c 20 61 6e 0a 2a 2a 20 53 51 4c 69 74  urs, an.** SQLit
37db0 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  e error code is 
37dc0 72 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65  returned and the
37dd0 20 62 6c 6f 62 20 68 61 6e 64 6c 65 20 69 73 20   blob handle is 
37de0 63 6f 6e 73 69 64 65 72 65 64 20 61 62 6f 72 74  considered abort
37df0 65 64 2e 0a 2a 2a 20 5e 41 6c 6c 20 73 75 62 73  ed..** ^All subs
37e00 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
37e10 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65  [sqlite3_blob_re
37e20 61 64 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ad()], [sqlite3_
37e30 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 6f 72  blob_write()] or
37e40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
37e50 62 5f 72 65 6f 70 65 6e 28 29 5d 20 6f 6e 20 61  b_reopen()] on a
37e60 6e 20 61 62 6f 72 74 65 64 20 62 6c 6f 62 20 68  n aborted blob h
37e70 61 6e 64 6c 65 20 69 6d 6d 65 64 69 61 74 65 6c  andle immediatel
37e80 79 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49  y return.** SQLI
37e90 54 45 5f 41 42 4f 52 54 2e 20 5e 43 61 6c 6c 69  TE_ABORT. ^Calli
37ea0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ng [sqlite3_blob
37eb0 5f 62 79 74 65 73 28 29 5d 20 6f 6e 20 61 6e 20  _bytes()] on an 
37ec0 61 62 6f 72 74 65 64 20 62 6c 6f 62 20 68 61 6e  aborted blob han
37ed0 64 6c 65 0a 2a 2a 20 61 6c 77 61 79 73 20 72 65  dle.** always re
37ee0 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
37ef0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
37f00 20 73 65 74 73 20 74 68 65 20 64 61 74 61 62 61   sets the databa
37f10 73 65 20 68 61 6e 64 6c 65 20 65 72 72 6f 72 20  se handle error 
37f20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
37f30 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45  ..*/.SQLITE_EXPE
37f40 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c  RIMENTAL int sql
37f50 69 74 65 33 5f 62 6c 6f 62 5f 72 65 6f 70 65 6e  ite3_blob_reopen
37f60 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c  (sqlite3_blob *,
37f70 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
37f80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37f90 3a 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48  : Close A BLOB H
37fa0 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f  andle.**.** ^Clo
37fb0 73 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f  ses an open [BLO
37fc0 42 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a  B handle]..**.**
37fd0 20 5e 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42   ^Closing a BLOB
37fe0 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65   shall cause the
37ff0 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63   current transac
38000 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a  tion to commit.*
38010 2a 20 69 66 20 74 68 65 72 65 20 61 72 65 20 6e  * if there are n
38020 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e  o other BLOBs, n
38030 6f 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61 72  o pending prepar
38040 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61  ed statements, a
38050 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  nd the.** databa
38060 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
38070 20 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20   in [autocommit 
38080 6d 6f 64 65 5d 2e 0a 2a 2a 20 5e 49 66 20 61 6e  mode]..** ^If an
38090 79 20 77 72 69 74 65 73 20 77 65 72 65 20 6d 61  y writes were ma
380a0 64 65 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20  de to the BLOB, 
380b0 74 68 65 79 20 6d 69 67 68 74 20 62 65 20 68 65  they might be he
380c0 6c 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75  ld in cache.** u
380d0 6e 74 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f  ntil the close o
380e0 70 65 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79  peration if they
380f0 20 77 69 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a   will fit..**.**
38100 20 5e 28 43 6c 6f 73 69 6e 67 20 74 68 65 20 42   ^(Closing the B
38110 4c 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63 65 73  LOB often forces
38120 20 74 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20   the changes.** 
38130 6f 75 74 20 74 6f 20 64 69 73 6b 20 61 6e 64 20  out to disk and 
38140 73 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20 65 72  so if any I/O er
38150 72 6f 72 73 20 6f 63 63 75 72 2c 20 74 68 65 79  rors occur, they
38160 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63   will likely occ
38170 75 72 0a 2a 2a 20 61 74 20 74 68 65 20 74 69 6d  ur.** at the tim
38180 65 20 77 68 65 6e 20 74 68 65 20 42 4c 4f 42 20  e when the BLOB 
38190 69 73 20 63 6c 6f 73 65 64 2e 20 20 41 6e 79 20  is closed.  Any 
381a0 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
381b0 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73  r during.** clos
381c0 69 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65 64  ing are reported
381d0 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72   as a non-zero r
381e0 65 74 75 72 6e 20 76 61 6c 75 65 2e 29 5e 0a 2a  eturn value.)^.*
381f0 2a 0a 2a 2a 20 5e 28 54 68 65 20 42 4c 4f 42 20  *.** ^(The BLOB 
38200 69 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64  is closed uncond
38210 69 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e  itionally.  Even
38220 20 69 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   if this routine
38230 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65   returns.** an e
38240 72 72 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 42  rror code, the B
38250 4c 4f 42 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f  LOB is still clo
38260 73 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61  sed.)^.**.** ^Ca
38270 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
38280 6e 65 20 77 69 74 68 20 61 20 6e 75 6c 6c 20 70  ne with a null p
38290 6f 69 6e 74 65 72 20 28 73 75 63 68 20 61 73 20  ointer (such as 
382a0 77 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  would be returne
382b0 64 0a 2a 2a 20 62 79 20 61 20 66 61 69 6c 65 64  d.** by a failed
382c0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
382d0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29 20  3_blob_open()]) 
382e0 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
382f0 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  -op..*/.int sqli
38300 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73  te3_blob_close(s
38310 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a  qlite3_blob *);.
38320 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
38330 20 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65   Return The Size
38340 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42   Of An Open BLOB
38350 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 73 20  .**.** ^Returns 
38360 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65  the size in byte
38370 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 61 63  s of the BLOB ac
38380 63 65 73 73 69 62 6c 65 20 76 69 61 20 74 68 65  cessible via the
38390 20 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c   .** successfull
383a0 79 20 6f 70 65 6e 65 64 20 5b 42 4c 4f 42 20 68  y opened [BLOB h
383b0 61 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e  andle] in its on
383c0 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54  ly argument.  ^T
383d0 68 65 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 61  he.** incrementa
383e0 6c 20 62 6c 6f 62 20 49 2f 4f 20 72 6f 75 74 69  l blob I/O routi
383f0 6e 65 73 20 63 61 6e 20 6f 6e 6c 79 20 72 65 61  nes can only rea
38400 64 20 6f 72 20 6f 76 65 72 77 72 69 74 69 6e 67  d or overwriting
38410 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 62 6c 6f   existing.** blo
38420 62 20 63 6f 6e 74 65 6e 74 3b 20 74 68 65 79 20  b content; they 
38430 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
38440 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62  e size of a blob
38450 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
38460 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20  tine only works 
38470 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  on a [BLOB handl
38480 65 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65  e] which has bee
38490 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20  n created.** by 
384a0 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  a prior successf
384b0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
384c0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
384d0 20 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e   and which has n
384e0 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65  ot.** been close
384f0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c  d by [sqlite3_bl
38500 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61  ob_close()].  Pa
38510 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  ssing any other 
38520 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f  pointer in.** to
38530 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
38540 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
38550 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
38560 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
38570 76 69 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  vior..*/.int sql
38580 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
38590 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b  sqlite3_blob *);
385a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
385b0 3a 20 52 65 61 64 20 44 61 74 61 20 46 72 6f 6d  : Read Data From
385c0 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e   A BLOB Incremen
385d0 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  tally.**.** ^(Th
385e0 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  is function is u
385f0 73 65 64 20 74 6f 20 72 65 61 64 20 64 61 74 61  sed to read data
38600 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b 42   from an open [B
38610 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 74 6f  LOB handle] into
38620 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70   a.** caller-sup
38630 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 4e 20  plied buffer. N 
38640 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72  bytes of data ar
38650 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 75  e copied into bu
38660 66 66 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74  ffer Z.** from t
38670 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74  he open BLOB, st
38680 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74  arting at offset
38690 20 69 4f 66 66 73 65 74 2e 29 5e 0a 2a 2a 0a 2a   iOffset.)^.**.*
386a0 2a 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f 66  * ^If offset iOf
386b0 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61  fset is less tha
386c0 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74  n N bytes from t
386d0 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c  he end of the BL
386e0 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  OB,.** [SQLITE_E
386f0 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65  RROR] is returne
38700 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73  d and no data is
38710 20 72 65 61 64 2e 20 20 5e 49 66 20 4e 20 6f 72   read.  ^If N or
38720 20 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c   iOffset is.** l
38730 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b  ess than zero, [
38740 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73  SQLITE_ERROR] is
38750 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f   returned and no
38760 20 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a   data is read..*
38770 2a 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 74  * ^The size of t
38780 68 65 20 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e  he blob (and hen
38790 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76  ce the maximum v
387a0 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65  alue of N+iOffse
387b0 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74  t).** can be det
387c0 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ermined using th
387d0 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
387e0 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61  bytes()] interfa
387f0 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74  ce..**.** ^An at
38800 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 66 72  tempt to read fr
38810 6f 6d 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42  om an expired [B
38820 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c  LOB handle] fail
38830 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72  s with an.** err
38840 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49  or code of [SQLI
38850 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a  TE_ABORT]..**.**
38860 20 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 73   ^(On success, s
38870 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
38880 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
38890 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69  E_OK..** Otherwi
388a0 73 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  se, an [error co
388b0 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e  de] or an [exten
388c0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20  ded error code] 
388d0 69 73 20 72 65 74 75 72 6e 65 6