/ Hex Artifact Content
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Artifact ff950aef7b378963c67add42dda5d446a0b7330e:


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: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
31c0: 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67  s relayed throug
31d0: 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67  h to the 1st arg
31e0: 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a  ument of each.**
31f0: 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61   callback invoca
3200: 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63  tion.  ^If the c
3210: 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20  allback pointer 
3220: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3230: 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ).** is NULL, th
3240: 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69  en no callback i
3250: 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61  s ever invoked a
3260: 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61  nd result rows a
3270: 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a  re.** ignored..*
3280: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f  *.** ^If an erro
3290: 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65  r occurs while e
32a0: 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51  valuating the SQ
32b0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73  L statements pas
32c0: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  sed into.** sqli
32d0: 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e  te3_exec(), then
32e0: 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
32f0: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d  e current statem
3300: 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a  ent stops and.**
3310: 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74   subsequent stat
3320: 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70  ements are skipp
3330: 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68  ed.  ^If the 5th
3340: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3350: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3360: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
3370: 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61   any error messa
3380: 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  ge is written in
3390: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
33a0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
33b0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
33c0: 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68  d passed back th
33d0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
33e0: 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61  rameter..** To a
33f0: 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b  void memory leak
3400: 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  s, the applicati
3410: 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65  on should invoke
3420: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
3430: 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65  ].** on error me
3440: 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65  ssage strings re
3450: 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74  turned through t
3460: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3470: 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65   of.** of sqlite
3480: 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20 74  3_exec() after t
3490: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
34a0: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f   string is no lo
34b0: 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20  nger needed..** 
34c0: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61  ^If the 5th para
34d0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
34e0: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
34f0: 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72  ULL and no error
3500: 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e  s.** occur, then
3510: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3520: 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72  sets the pointer
3530: 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72 61   in its 5th para
3540: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c  meter to.** NULL
3550: 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
3560: 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  g..**.** ^If an 
3570: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3580: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
3590: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71  non-zero, the sq
35a0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
35b0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
35c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74  SQLITE_ABORT wit
35d0: 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  hout invoking th
35e0: 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e  e callback again
35f0: 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20   and.** without 
3600: 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73  running any subs
3610: 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65  equent SQL state
3620: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
3630: 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  e 2nd argument t
3640: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78  o the sqlite3_ex
3650: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75  ec() callback fu
3660: 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a  nction is the.**
3670: 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
3680: 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
3690: 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67 75  .  ^The 3rd argu
36a0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
36b0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61  te3_exec().** ca
36c0: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72  llback is an arr
36d0: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
36e0: 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e  o strings obtain
36f0: 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a  ed as if from.**
3700: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
3710: 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f  _text()], one fo
3720: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20  r each column.  
3730: 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f  ^If an element o
3740: 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  f a.** result ro
3750: 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  w is NULL then t
3760: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
3770: 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
3780: 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74  for the.** sqlit
3790: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
37a0: 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ck is a NULL poi
37b0: 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20  nter.  ^The 4th 
37c0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
37d0: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
37e0: 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  ) callback is an
37f0: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3800: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68  rs to strings wh
3810: 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72  ere each.** entr
3820: 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68 65  y represents the
3830: 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70   name of corresp
3840: 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f  onding result co
3850: 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64  lumn as obtained
3860: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3870: 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d  3_column_name()]
3880: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
3890: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
38a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38b0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
38c0: 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  r, a pointer.** 
38d0: 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
38e0: 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72  ng, or a pointer
38f0: 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f   that contains o
3900: 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61  nly whitespace a
3910: 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f  nd/or .** SQL co
3920: 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20  mments, then no 
3930: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
3940: 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64  re evaluated and
3950: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
3960: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e   is not changed.
3970: 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69  .**.** Restricti
3980: 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ons:.**.** <ul>.
3990: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
39a0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73  ication must ins
39b0: 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73 74  ure that the 1st
39c0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
39d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
39e0: 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64 20       is a valid 
39f0: 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  and open [databa
3a00: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
3a10: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3a20: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3a30: 20 63 6c 6f 73 65 20 5b 64 61 74 61 62 61 73 65   close [database
3a40: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
3a50: 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
3a60: 20 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65    the 1st parame
3a70: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3a80: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
3a90: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
3aa0: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  nning..** <li> T
3ab0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3ac0: 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74  ust not modify t
3ad0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3ae0: 20 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74   text passed int
3af0: 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e  o.**      the 2n
3b00: 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
3b10: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
3b20: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
3b30: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
3b40: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ul>.*/.int s
3b50: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73  qlite3_exec(.  s
3b60: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
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 2f 2a 20 41 6e 20            /* An 
3b90: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
3ba0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
3bb0: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ql,             
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
3bd0: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
3be0: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  ated */.  int (*
3bf0: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3c00: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a  int,char**,char*
3c10: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b  *),  /* Callback
3c20: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
3c30: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20  oid *,          
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 2f 2a 20 31 73 74            /* 1st
3c60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
3c70: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20  lback */.  char 
3c80: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20  **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 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
3cb0: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
3cc0: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
3cd0: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f  I3REF: Result Co
3ce0: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
3cf0: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f   SQLITE_OK {erro
3d00: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63  r code} {error c
3d10: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
3d20: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d  S: {result code}
3d30: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a   {result codes}.
3d40: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
3d50: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
3d60: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
3d70: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
3d80: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
3d90: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
3da0: 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65   indicates succe
3db0: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a  ss or failure..*
3dc0: 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63  *.** New error c
3dd0: 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  odes may be adde
3de0: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
3df0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
3e00: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
3e10: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
3e20: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
3e30: 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a 2a 2a 20  sult codes],.** 
3e40: 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e  [sqlite3_vtab_on
3e50: 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 5b 53 51  _conflict()] [SQ
3e60: 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20  LITE_ROLLBACK | 
3e70: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 0a 2a  result codes]..*
3e80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e90: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3ea0: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3eb0: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3ec0: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3ed0: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ee0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3ef0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3f00: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3f10: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3f20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3f30: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f40: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f50: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f70: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f80: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f90: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3fa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3fb0: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3fc0: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3fd0: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fe0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3ff0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
4000: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
4010: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
4020: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
4030: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4040: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4050: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4060: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4070: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4080: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4090: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
40a0: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
40b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
40c0: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
40d0: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40e0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40f0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
4100: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
4110: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
4120: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
4130: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4140: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4150: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4160: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4170: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4180: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4190: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
41a0: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
41b0: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
41c0: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
41d0: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41f0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
4200: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
4210: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
4220: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
4230: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
4240: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
4250: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
4260: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
4270: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
4280: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
4290: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
42a0: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
42b0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
42c0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
42d0: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
42e0: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
42f0: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
4300: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4310: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
4320: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
4330: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
4340: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
4350: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
4360: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4370: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
4380: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4390: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
43a0: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
43b0: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
43c0: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
43d0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
43e0: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
43f0: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
4400: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
4410: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4420: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
4430: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
4440: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
4450: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
4460: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
4470: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
4480: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
4490: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
44a0: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
44b0: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
44c0: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
44d0: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
44e0: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
44f0: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
4500: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
4510: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4520: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
4530: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
4540: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
4550: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4560: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4570: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4580: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4590: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
45a0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
45b0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
45c0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
45d0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
45e0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
45f0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4600: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4610: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4620: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4630: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4640: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4650: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4660: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4670: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4680: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4690: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
46a0: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
46b0: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
46c0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
46d0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
46e0: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d  nded error code}
46f0: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
4700: 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f   codes}.** KEYWO
4710: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
4720: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74  esult code} {ext
4730: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4740: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  es}.**.** In its
4750: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
4760: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4770: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4780: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74  rn one of 26 int
4790: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eger.** [SQLITE_
47a0: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
47b0: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  s].  However, ex
47c0: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
47d0: 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a  wn that many of.
47e0: 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  ** these result 
47f0: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
4800: 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  arse-grained.  T
4810: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
4820: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
4830: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
4840: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67  problems as prog
4850: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69  rammers might li
4860: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
4870: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
4880: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
4890: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
48a0: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e  version 3.3.8 an
48b0: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
48c0: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
48d0: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
48e0: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
48f0: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
4900: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
4910: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
4920: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
4930: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e  ult codes are en
4940: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
4950: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
4960: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4970: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
4980: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
4990: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
49a0: 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a  des()] API..**.*
49b0: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76  * Some of the av
49c0: 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64  ailable extended
49d0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
49e0: 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a  e listed here..*
49f0: 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74  * One may expect
4a00: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
4a10: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4a20: 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70  odes will be exp
4a30: 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65  and.** over time
4a40: 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
4a50: 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72   uses extended r
4a60: 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75  esult codes shou
4a70: 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20  ld expect.** to 
4a80: 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63  see new result c
4a90: 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72  odes in future r
4aa0: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
4ab0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  e..**.** The SQL
4ac0: 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f  ITE_OK result co
4ad0: 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65  de will never be
4ae0: 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77   extended.  It w
4af0: 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  ill always.** be
4b00: 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a   exactly zero..*
4b10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b20: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20  _IOERR_READ     
4b30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4b40: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29  _IOERR | (1<<8))
4b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b60: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
4b70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4b80: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a  IOERR | (2<<8)).
4b90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4ba0: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20  OERR_WRITE      
4bb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4bc0: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OERR | (3<<8)).#
4bd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4be0: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  ERR_FSYNC       
4bf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4c00: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  ERR | (4<<8)).#d
4c10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4c20: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20  RR_DIR_FSYNC    
4c30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4c40: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  RR | (5<<8)).#de
4c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4c60: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20  R_TRUNCATE      
4c70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4c80: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  R | (6<<8)).#def
4c90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4ca0: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20  _FSTAT          
4cb0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4cc0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
4cd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4ce0: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  UNLOCK          
4cf0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4d00: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
4d10: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
4d20: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  DLOCK           
4d30: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4d40: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
4d50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45   SQLITE_IOERR_DE
4d60: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
4d70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4d80: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
4d90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c   SQLITE_IOERR_BL
4da0: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20  OCKED           
4db0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4dc0: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (11<<8)).#define
4dd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f   SQLITE_IOERR_NO
4de0: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20  MEM             
4df0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e00: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (12<<8)).#define
4e10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43   SQLITE_IOERR_AC
4e20: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20  CESS            
4e30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e40: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (13<<8)).#define
4e50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48   SQLITE_IOERR_CH
4e60: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20  ECKRESERVEDLOCK 
4e70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e80: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (14<<8)).#define
4e90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f   SQLITE_IOERR_LO
4ea0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CK              
4eb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4ec0: 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (15<<8)).#define
4ed0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c   SQLITE_IOERR_CL
4ee0: 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20  OSE             
4ef0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f00: 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (16<<8)).#define
4f10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4f20: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
4f30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f40: 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (17<<8)).#define
4f50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4f60: 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20  MOPEN           
4f70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f80: 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (18<<8)).#define
4f90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4fa0: 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  MSIZE           
4fb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4fc0: 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (19<<8)).#define
4fd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4fe0: 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  MLOCK           
4ff0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5000: 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (20<<8)).#define
5010: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5020: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
5030: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5040: 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (21<<8)).#define
5050: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45   SQLITE_IOERR_SE
5060: 45 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EK              
5070: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5080: 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (22<<8)).#define
5090: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53   SQLITE_LOCKED_S
50a0: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
50b0: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c  (SQLITE_LOCKED |
50c0: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
50d0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45  e SQLITE_BUSY_RE
50e0: 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20  COVERY          
50f0: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
5100: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69  |  (1<<8)).#defi
5110: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5120: 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20  EN_NOTEMPDIR    
5130: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5140: 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  EN | (1<<8)).#de
5150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
5160: 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20  UPT_VTAB        
5170: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52      (SQLITE_CORR
5180: 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  UPT | (1<<8)).#d
5190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
51a0: 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20  DONLY_RECOVERY  
51b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
51c0: 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a  DONLY | (1<<8)).
51d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
51e0: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b  EADONLY_CANTLOCK
51f0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5200: 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29  EADONLY | (2<<8)
5210: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
5220: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
5230: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
5240: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
5250: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
5260: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
5270: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
5280: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5290: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
52a0: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
52b0: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
52c0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
52d0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
52e0: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65  ] method..*/.#de
52f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5300: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
5310: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
5320: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5330: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5350: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
5360: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
5370: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5380: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5390: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
53a0: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
53b0: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
53c0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
53d0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
53e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
53f0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
5400: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
5410: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5420: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5430: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
5440: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
5450: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5460: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5470: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
5480: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
5490: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
54a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
54b0: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20  _URI            
54c0: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a    0x00000040  /*
54d0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
54e0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
54f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5500: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
5510: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
5520: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5530: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5540: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
5550: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
5560: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5570: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5580: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
5590: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
55a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
55b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
55c0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
55d0: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
55e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
55f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5600: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
5610: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
5620: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5630: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5640: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
5650: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
5660: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5670: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5680: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
5690: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
56a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
56b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
56c0: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
56d0: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
56e0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
56f0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5700: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5710: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
5720: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
5730: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5740: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5750: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5760: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
5770: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
5780: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5790: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
57a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
57b0: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
57c0: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
57d0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
57e0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
57f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5800: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
5810: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
5820: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a   VFS only */../*
5830: 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20   Reserved:      
5840: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5850: 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f     0x00F00000 */
5860: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5870: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
5880: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
5890: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
58a0: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
58b0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
58c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
58d0: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
58e0: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
58f0: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
5900: 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  he these.** bit 
5910: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
5920: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
5930: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
5940: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
5950: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
5960: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
5970: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5980: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
5990: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
59a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
59b0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
59c0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
59d0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
59e0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
59f0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5a00: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
5a10: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
5a20: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
5a30: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
5a40: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
5a50: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
5a60: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
5a70: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
5a80: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
5a90: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
5aa0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
5ab0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
5ac0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
5ad0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
5ae0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
5af0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
5b00: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
5b10: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
5b20: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
5b30: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
5b40: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
5b50: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
5b60: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
5b70: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
5b80: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
5b90: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
5ba0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
5bb0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
5bc0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
5bd0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5be0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
5bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5c00: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
5c10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5c20: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
5c30: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5c40: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
5c50: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20  _IOCAP_ATOMIC1K 
5c60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5c70: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65  00000004.#define
5c80: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5c90: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20  OMIC2K          
5ca0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a       0x00000008.
5cb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5cc0: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20  OCAP_ATOMIC4K   
5cd0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5ce0: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
5cf0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5d00: 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC8K            
5d10: 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64     0x00000020.#d
5d20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5d30: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20  AP_ATOMIC16K    
5d40: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5d50: 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0040.#define SQL
5d60: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5d70: 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  32K             
5d80: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66   0x00000080.#def
5d90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5da0: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20  _ATOMIC64K      
5db0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
5dc0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
5dd0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
5de0: 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30  END            0
5df0: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e  x00000200.#defin
5e00: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
5e10: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20  EQUENTIAL       
5e20: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30        0x00000400
5e30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e40: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
5e50: 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30  E_WHEN_OPEN  0x0
5e60: 30 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0000800../*.** C
5e70: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
5e80: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
5e90: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
5ea0: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
5eb0: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ec0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
5ed0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
5ee0: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
5ef0: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
5f00: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
5f10: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
5f20: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
5f30: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5f40: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
5f50: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
5f60: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
5f70: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
5f80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5f90: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
5fa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5fb0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
5fc0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
5fd0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
5fe0: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
5ff0: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
6000: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
6010: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
6020: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
6030: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
6040: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
6050: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6060: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
6070: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
6080: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
6090: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
60a0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
60b0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
60c0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
60d0: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
60e0: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
60f0: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
6100: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
6110: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
6120: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
6130: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
6140: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
6150: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
6160: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6170: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
6180: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
6190: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
61a0: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
61b0: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
61c0: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
61d0: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
61e0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
61f0: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
6200: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
6210: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
6220: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
6230: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
6240: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
6250: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
6260: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
6270: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
6280: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
6290: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
62a0: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
62b0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
62c0: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
62d0: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
62e0: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
62f0: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
6300: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
6310: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
6320: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
6330: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
6340: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
6350: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
6360: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
6370: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6380: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
6390: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
63a0: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
63b0: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
63c0: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
63d0: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
63e0: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
63f0: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
6400: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
6410: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
6420: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
6430: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
6440: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
6450: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
6460: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
6470: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
6480: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
6490: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
64a0: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
64b0: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
64c0: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
64d0: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
64e0: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
64f0: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
6500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
6510: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
6520: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
6530: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
6540: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
6550: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
6560: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
6570: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
6580: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
6590: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
65a0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
65b0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
65c0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
65d0: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
65e0: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
65f0: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
6600: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
6610: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
6620: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
6630: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
6640: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
6650: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
6660: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
6670: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
6680: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
6690: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
66a0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
66b0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
66c0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
66d0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
66e0: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
66f0: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
6700: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
6710: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
6720: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
6730: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6740: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
6750: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
6760: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
6770: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
6780: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
6790: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
67a0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
67b0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
67c0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
67d0: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
67e0: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
67f0: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
6800: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6810: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
6820: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
6830: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
6840: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6850: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
6860: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
6870: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
6880: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
6890: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
68a0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
68b0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
68c0: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
68d0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
68e0: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
68f0: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6900: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6910: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6920: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6930: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6940: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6950: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
6960: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
6970: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
6980: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
6990: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
69a0: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
69b0: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
69c0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
69d0: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
69e0: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
69f0: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
6a00: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
6a10: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
6a20: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
6a30: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
6a40: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
6a50: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
6a60: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
6a70: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
6a80: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
6a90: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
6aa0: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
6ab0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
6ac0: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
6ad0: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
6ae0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
6af0: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
6b00: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
6b10: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
6b20: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
6b30: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
6b40: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
6b50: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
6b60: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
6b70: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
6b80: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
6b90: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
6ba0: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
6bb0: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
6bc0: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
6bd0: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
6be0: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
6bf0: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
6c00: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
6c10: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
6c20: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6c30: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
6c40: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
6c50: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
6c60: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6c70: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
6c80: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
6c90: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
6ca0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
6cb0: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
6cc0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6cd0: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
6ce0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
6cf0: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
6d00: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
6d10: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
6d20: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
6d30: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
6d40: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
6d50: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
6d60: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
6d70: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
6d80: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
6d90: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
6da0: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
6db0: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
6dc0: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
6dd0: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
6de0: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
6df0: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
6e00: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
6e10: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
6e20: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
6e30: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
6e40: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
6e50: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
6e60: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
6e70: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
6e80: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
6e90: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
6ea0: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
6eb0: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
6ec0: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
6ed0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
6ee0: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
6ef0: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
6f00: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
6f10: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
6f20: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
6f30: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
6f40: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
6f50: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
6f60: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
6f70: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
6f80: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
6f90: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
6fa0: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
6fb0: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
6fc0: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
6fd0: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
6fe0: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
6ff0: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
7000: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
7010: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
7020: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
7030: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
7040: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
7050: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
7060: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
7070: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
7080: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
7090: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
70a0: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
70b0: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
70c0: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
70d0: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
70e0: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
70f0: 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  A [SQLITE_FCNTL_
7100: 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74  LOCKSTATE | list
7110: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
7120: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
7130: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
7140: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
7150: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
7160: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
7170: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
7180: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
7190: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
71a0: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46  d conflicts.  VF
71b0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
71c0: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  s should.** retu
71d0: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  rn [SQLITE_NOTFO
71e0: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f  UND] for file co
71f0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68  ntrol opcodes th
7200: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
7210: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a  * recognize..**.
7220: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
7230: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
7240: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
7250: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
7260: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
7270: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
7280: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
7290: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
72a0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
72b0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
72c0: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
72d0: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
72e0: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
72f0: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
7300: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
7310: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
7320: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
7330: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
7340: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
7350: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
7360: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
7370: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7380: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
7390: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
73a0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
73b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
73c0: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
73d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
73e0: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
73f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7400: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
7410: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7420: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
7430: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7440: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
7450: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7460: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
7470: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7480: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
7490: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
74a0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
74b0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
74c0: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
74d0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
74e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
74f0: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
7500: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
7510: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
7520: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
7530: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
7540: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
7550: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
7560: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
7570: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
7580: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
7590: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
75a0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
75b0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
75c0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
75d0: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
75e0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
75f0: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
7600: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
7610: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
7620: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
7630: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
7640: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
7650: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
7660: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
7670: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
7680: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
7690: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
76a0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
76b0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
76c0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
76d0: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
76e0: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
76f0: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
7700: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
7710: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61  )..**.** If xRea
7720: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49  d() returns SQLI
7730: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
7740: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f  EAD it must also
7750: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20   fill.** in the 
7760: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20  unread portions 
7770: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69  of the buffer wi
7780: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53  th zeros.  A VFS
7790: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74   that.** fails t
77a0: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
77b0: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65  t reads might se
77c0: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77  em to work.  How
77d0: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65  ever,.** failure
77e0: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
77f0: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65  ort reads will e
7800: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74  ventually lead t
7810: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  o.** database co
7820: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  rruption..*/.typ
7830: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
7840: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73  te3_io_methods s
7850: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7860: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
7870: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  3_io_methods {. 
7880: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
7890: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
78a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
78b0: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71   int (*xRead)(sq
78c0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69  lite3_file*, voi
78d0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
78e0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
78f0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69  t);.  int (*xWri
7900: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
7910: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
7920: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
7930: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
7940: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74    int (*xTruncat
7950: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7960: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
7970: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  size);.  int (*x
7980: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69  Sync)(sqlite3_fi
7990: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  le*, int flags);
79a0: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69  .  int (*xFileSi
79b0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
79c0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
79d0: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20   *pSize);.  int 
79e0: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  (*xLock)(sqlite3
79f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
7a00: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73  int (*xUnlock)(s
7a10: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
7a20: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65  t);.  int (*xChe
7a30: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28  ckReservedLock)(
7a40: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7a50: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
7a60: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72  int (*xFileContr
7a70: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ol)(sqlite3_file
7a80: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20  *, int op, void 
7a90: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  *pArg);.  int (*
7aa0: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c  xSectorSize)(sql
7ab0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
7ac0: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72  nt (*xDeviceChar
7ad0: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c  acteristics)(sql
7ae0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f  ite3_file*);.  /
7af0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
7b00: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
7b10: 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74  rsion 1 */.  int
7b20: 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69   (*xShmMap)(sqli
7b30: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69  te3_file*, int i
7b40: 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e  Pg, int pgsz, in
7b50: 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65  t, void volatile
7b60: 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  **);.  int (*xSh
7b70: 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  mLock)(sqlite3_f
7b80: 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74  ile*, int offset
7b90: 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61  , int n, int fla
7ba0: 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53  gs);.  void (*xS
7bb0: 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74  hmBarrier)(sqlit
7bc0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
7bd0: 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71   (*xShmUnmap)(sq
7be0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7bf0: 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20   deleteFlag);.  
7c00: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
7c10: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
7c20: 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a  ersion 2 */.  /*
7c30: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
7c40: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
7c50: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
7c60: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
7c70: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
7c80: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
7c90: 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54   Opcodes.**.** T
7ca0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
7cb0: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
7cc0: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
7cd0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
7ce0: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
7cf0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
7d00: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
7d10: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
7d20: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
7d30: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
7d40: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
7d50: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
7d60: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
7d70: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
7d80: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
7d90: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
7da0: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
7db0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
7dc0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
7dd0: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
7de0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
7df0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
7e00: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
7e10: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
7e20: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
7e30: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
7e40: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
7e50: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
7e60: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
7e70: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
7e80: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
7e90: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
7ea0: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
7eb0: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
7ec0: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
7ed0: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
7ee0: 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  .** is defined..
7ef0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
7f00: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
7f10: 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  T] opcode is use
7f20: 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67  d by SQLite to g
7f30: 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c  ive the VFS.** l
7f40: 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68  ayer a hint of h
7f50: 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74  ow large the dat
7f60: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
7f70: 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e  grow to be durin
7f80: 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  g the.** current
7f90: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54   transaction.  T
7fa0: 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20  his hint is not 
7fb0: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
7fc0: 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74   accurate but it
7fd0: 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f  .** is often clo
7fe0: 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79  se.  The underly
7ff0: 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68  ing VFS might ch
8000: 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63  oose to prealloc
8010: 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ate database.** 
8020: 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64  file space based
8030: 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e   on this hint in
8040: 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77   order to help w
8050: 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74  rites to the dat
8060: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75  abase.** file ru
8070: 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  n faster..**.** 
8080: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8090: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70  L_CHUNK_SIZE] op
80a0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
80b0: 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65  request that the
80c0: 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20   VFS.** extends 
80d0: 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68  and truncates th
80e0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
80f0: 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73  in chunks of a s
8100: 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ize specified.**
8110: 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68   by the user. Th
8120: 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
8130: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69  t to [sqlite3_fi
8140: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68  le_control()] sh
8150: 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74  ould .** point t
8160: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79  o an integer (ty
8170: 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69  pe int) containi
8180: 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b  ng the new chunk
8190: 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20  -size to use.** 
81a0: 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65  for the nominate
81b0: 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f  d database. Allo
81c0: 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  cating database 
81d0: 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61  file space in la
81e0: 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73  rge.** chunks (s
81f0: 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65  ay 1MB at a time
8200: 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69  ), may reduce fi
8210: 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65  le-system fragme
8220: 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69  ntation and.** i
8230: 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
8240: 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65  ce on some syste
8250: 6d 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ms..**.** The [S
8260: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
8270: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
8280: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
8290: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
82a0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
82b0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
82c0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70  ociated with a p
82d0: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
82e0: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
82f0: 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69  .  See the [sqli
8300: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
8310: 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  ()] documentatio
8320: 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  n for.** additio
8330: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
8340: 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51  .**.** ^(The [SQ
8350: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
8360: 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 20  OMITTED] opcode 
8370: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74  is generated int
8380: 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51  ernally by.** SQ
8390: 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74 6f  Lite and sent to
83a0: 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 6c   all VFSes in pl
83b0: 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f  ace of a call to
83c0: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
83d0: 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 61  d.** when the da
83e0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
83f0: 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73 79  n has [PRAGMA sy
8400: 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74  nchronous] set t
8410: 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65  o OFF.)^.** Some
8420: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
8430: 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  es need this sig
8440: 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nal in order to 
8450: 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c  operate correctl
8460: 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d  y.** when [PRAGM
8470: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20  A synchronous | 
8480: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
8490: 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c 20  us=OFF] is set, 
84a0: 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53  but most .** VFS
84b0: 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  es do not need t
84c0: 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 73  his signal and s
84d0: 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69  hould silently i
84e0: 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64  gnore this opcod
84f0: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  e..** Applicatio
8500: 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61  ns should not ca
8510: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ll [sqlite3_file
8520: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68  _control()] with
8530: 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   this.** opcode 
8540: 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20  as doing so may 
8550: 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72  disrupt the oper
8560: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
8570: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a  cialized VFSes.*
8580: 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  * that do requir
8590: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54  e it.  .**.** ^T
85a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
85b0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
85c0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
85d0: 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74  to configure aut
85e0: 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20  omatic.** retry 
85f0: 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72  counts and inter
8600: 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e  vals for certain
8610: 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74   disk I/O operat
8620: 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ions for the.** 
8630: 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e  windows [VFS] in
8640: 20 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 74   order to work t
8650: 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74  o provide robust
8660: 6e 65 73 73 20 61 67 61 69 6e 73 74 0a 2a 2a 20  ness against.** 
8670: 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72  anti-virus progr
8680: 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ams.  By default
8690: 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46  , the windows VF
86a0: 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c  S will retry fil
86b0: 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20  e read,.** file 
86c0: 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20  write, and file 
86d0: 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e  delete operation
86e0: 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73  s up to 10 times
86f0: 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a  , with a delay.*
8700: 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63  * of 25 millisec
8710: 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20  onds before the 
8720: 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20  first retry and 
8730: 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69  with the delay i
8740: 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20  ncreasing.** by 
8750: 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35  an additional 25
8760: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69   milliseconds wi
8770: 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65  th each subseque
8780: 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a  nt retry.  This.
8790: 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73  ** opcode allows
87a0: 20 74 68 6f 73 65 20 74 6f 20 76 61 6c 75 65 73   those to values
87b0: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
87c0: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
87d0: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
87e0: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
87f0: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
8800: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
8810: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
8820: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
8830: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
8840: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
8850: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
8860: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
8870: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
8880: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
8890: 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79   i the new retry
88a0: 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73   count and the s
88b0: 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72  econd.** integer
88c0: 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20   is the delay.  
88d0: 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65  If either intege
88e0: 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
88f0: 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a  hen the setting.
8900: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
8910: 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68  d but instead th
8920: 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
8930: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73   that setting is
8940: 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f   written.** into
8950: 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79   the array entry
8960: 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63  , allowing the c
8970: 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74  urrent retry set
8980: 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69  tings to be.** i
8990: 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68  nterrogated.  Th
89a0: 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65  e zDbName parame
89b0: 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  ter is ignored..
89c0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
89d0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
89e0: 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20  _WAL] opcode is 
89f0: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
8a00: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
8a10: 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72  istent [WAL | Wr
8a20: 69 74 65 20 41 48 65 61 64 20 4c 6f 67 5d 20 73  ite AHead Log] s
8a30: 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61  etting.  By defa
8a40: 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61  ult, the auxilia
8a50: 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61  ry.** write ahea
8a60: 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64  d log and shared
8a70: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73   memory files us
8a80: 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69  ed for transacti
8a90: 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72  on control.** ar
8aa0: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
8ab0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
8ac0: 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69   latest connecti
8ad0: 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  on to the databa
8ae0: 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53  se.** closes.  S
8af0: 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e  etting persisten
8b00: 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65  t WAL mode cause
8b10: 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f  s those files to
8b20: 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a   persist after.*
8b30: 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73  * close.  Persis
8b40: 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69  ting the files i
8b50: 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74  s useful when ot
8b60: 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68  her processes th
8b70: 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76  at do not.** hav
8b80: 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69  e write permissi
8b90: 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74  on on the direct
8ba0: 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ory containing t
8bb0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8bc0: 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64   want.** to read
8bd0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
8be0: 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61  le, as the WAL a
8bf0: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
8c00: 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73   files must exis
8c10: 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f  t.** in order fo
8c20: 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  r the database t
8c30: 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20  o be readable.  
8c40: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
8c50: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
8c60: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
8c70: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
8c80: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
8c90: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
8ca0: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
8cb0: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
8cc0: 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  isable persisten
8cd0: 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20  t WAL mode or 1 
8ce0: 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73  to enable persis
8cf0: 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65  tent.** WAL mode
8d00: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
8d10: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
8d20: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
8d30: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
8d40: 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65  .** WAL persiste
8d50: 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  nce setting..**.
8d60: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
8d70: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
8d80: 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b   opcode is invok
8d90: 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74  ed by SQLite aft
8da0: 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20  er opening.** a 
8db0: 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f  write transactio
8dc0: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
8dd0: 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73  at, unless it is
8de0: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72   rolled back for
8df0: 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c   some.** reason,
8e00: 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61   the entire data
8e10: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62  base file will b
8e20: 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79  e overwritten by
8e30: 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a   the current .**
8e40: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68   transaction. Th
8e50: 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41  is is used by VA
8e60: 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e  CUUM operations.
8e70: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
8e80: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
8e90: 54 45 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  TE        1.#def
8ea0: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c  ine SQLITE_GET_L
8eb0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
8ec0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
8ed0: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_SET_LOCKPROXY
8ee0: 46 49 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66  FILE      3.#def
8ef0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f  ine SQLITE_LAST_
8f00: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
8f10: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
8f20: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
8f30: 4e 54 20 20 20 20 20 20 20 20 35 0a 23 64 65 66  NT        5.#def
8f40: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
8f50: 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20  _CHUNK_SIZE     
8f60: 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
8f70: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
8f80: 49 4e 54 45 52 20 20 20 20 20 37 0a 23 64 65 66  INTER     7.#def
8f90: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
8fa0: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20  _SYNC_OMITTED   
8fb0: 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
8fc0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
8fd0: 56 5f 52 45 54 52 59 20 20 20 39 0a 23 64 65 66  V_RETRY   9.#def
8fe0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
8ff0: 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20  _PERSIST_WAL    
9000: 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
9010: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
9020: 54 45 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a  TE       11../*.
9030: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
9040: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
9050: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
9060: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
9070: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
9080: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
9090: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
90a0: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
90b0: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
90c0: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
90d0: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
90e0: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
90f0: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
9100: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
9110: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
9120: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
9130: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
9140: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
9150: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
9160: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
9170: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
9180: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
9190: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
91a0: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
91b0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
91c0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
91d0: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
91e0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
91f0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
9200: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
9210: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
9220: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
9230: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
9240: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
9250: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
9260: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
9270: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
9280: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
9290: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
92a0: 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b  ".  See.** the [
92b0: 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65  VFS | VFS docume
92c0: 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72  ntation] for fur
92d0: 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ther information
92e0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ..**.** The valu
92f0: 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f  e of the iVersio
9300: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69  n field is initi
9310: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62  ally 1 but may b
9320: 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66  e larger in.** f
9330: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
9340: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74  f SQLite.  Addit
9350: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79  ional fields may
9360: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
9370: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77  this.** object w
9380: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e  hen the iVersion
9390: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61   value is increa
93a0: 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  sed.  Note that 
93b0: 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  the structure.**
93c0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
93d0: 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67  vfs object chang
93e0: 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61  es in the transa
93f0: 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ction between.**
9400: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
9410: 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20  3.5.9 and 3.6.0 
9420: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72  and yet the iVer
9430: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e  sion field was n
9440: 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a  ot.** modified..
9450: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
9460: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
9470: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
9480: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
9490: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
94a0: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
94b0: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
94c0: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
94d0: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
94e0: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
94f0: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
9500: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
9510: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
9520: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
9530: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
9540: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
9550: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
9560: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
9570: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
9580: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
9590: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
95a0: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
95b0: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
95c0: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
95d0: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
95e0: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
95f0: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
9600: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
9610: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
9620: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
9630: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
9640: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
9650: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
9660: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
9670: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
9680: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
9690: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
96a0: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
96b0: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
96c0: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
96d0: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
96e0: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
96f0: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
9700: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
9710: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
9720: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
9730: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
9740: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
9750: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
9760: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
9770: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
9780: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
9790: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
97a0: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
97b0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
97c0: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
97d0: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
97e0: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
97f0: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
9800: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
9810: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53  fs.xOpen]].** ^S
9820: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
9830: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
9840: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
9850: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
9860: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
9870: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
9880: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
9890: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69  ullPathname() wi
98a0: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73  th an optional s
98b0: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20  uffix added..** 
98c0: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20  ^If a suffix is 
98d0: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69  added to the zFi
98e0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
98f0: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  , it will.** con
9900: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65  sist of a single
9910: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66   "-" character f
9920: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f  ollowed by no mo
9930: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 30 20 61 6c  re than.** 10 al
9940: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f  phanumeric and/o
9950: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73  r "-" characters
9960: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72  ..** ^SQLite fur
9970: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
9980: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
9990: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
99a0: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
99b0: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
99c0: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
99d0: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
99e0: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
99f0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
9a00: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
9a10: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
9a20: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
9a30: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
9a40: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
9a50: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
9a60: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
9a70: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
9a80: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69  meter to xOpen i
9a90: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
9aa0: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
9ab0: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
9ac0: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
9ad0: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
9ae0: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a   ^Whenever the .
9af0: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
9b00: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
9b10: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
9b20: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
9b30: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
9b40: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
9b50: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
9b60: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
9b70: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
9b80: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
9b90: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
9ba0: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
9bb0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
9bc0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
9bd0: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
9be0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
9bf0: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
9c00: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
9c10: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
9c20: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
9c30: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
9c40: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
9c50: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
9c60: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
9c70: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
9c80: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
9c90: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
9ca0: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
9cb0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
9cc0: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
9cd0: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
9ce0: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
9cf0: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c  ** ^(SQLite will
9d00: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
9d10: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
9d20: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
9d30: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
9d40: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
9d50: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
9d60: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
9d70: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
9d80: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
9d90: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
9da0: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
9db0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
9dc0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
9dd0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
9de0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
9df0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
9e00: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
9e10: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
9e20: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
9e30: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
9e40: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
9e50: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
9e60: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
9e70: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f  _OPEN_WAL].** </
9e80: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
9e90: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
9ea0: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
9eb0: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
9ec0: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
9ed0: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
9ee0: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
9ef0: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
9f00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
9f10: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
9f20: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
9f30: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
9f40: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
9f50: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
9f60: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
9f70: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
9f80: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
9f90: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
9fa0: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
9fb0: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
9fc0: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
9fd0: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
9fe0: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
9ff0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
a000: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
a010: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
a020: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
a030: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
a040: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
a050: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
a060: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
a070: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
a080: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
a090: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
a0a0: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
a0b0: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
a0c0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
a0d0: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
a0e0: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
a0f0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
a100: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
a110: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
a120: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
a130: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
a140: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
a150: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
a160: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
a170: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
a180: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
a190: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
a1a0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
a1b0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
a1c0: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
a1d0: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61   for TEMP databa
a1e0: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f  ses and their jo
a1f0: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e  urnals, transien
a200: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20  t.** databases, 
a210: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  and subjournals.
a220: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
a230: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
a240: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
a250: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
a260: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
a270: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
a280: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
a290: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
a2a0: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
a2b0: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
a2c0: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
a2d0: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
a2e0: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
a2f0: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
a300: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
a310: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
a320: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
a330: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
a340: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
a350: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
a360: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
a370: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
a380: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
a390: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
a3a0: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
a3b0: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
a3c0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
a3d0: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
a3e0: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
a3f0: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
a400: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73  *.** ^At least s
a410: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
a420: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
a430: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
a440: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
a450: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
a460: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
a470: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
a480: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
a490: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
a4a0: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
a4b0: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
a4c0: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
a4d0: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
a4e0: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
a4f0: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
a500: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
a510: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
a520: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
a530: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
a540: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
a550: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
a560: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
a570: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
a580: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
a590: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
a5a0: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
a5b0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
a5c0: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
a5d0: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
a5e0: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
a5f0: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
a600: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
a610: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
a620: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
a630: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
a640: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a  _vfs.xAccess]].*
a650: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67  * ^The flags arg
a660: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
a670: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
a680: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
a690: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
a6a0: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
a6b0: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
a6c0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
a6d0: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
a6e0: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
a6f0: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
a700: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
a710: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
a720: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
a730: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
a740: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
a750: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
a760: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
a770: 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ry..**.** ^SQLit
a780: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
a790: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
a7a0: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
a7b0: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
a7c0: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
a7d0: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20  lPathname.  The 
a7e0: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68  exact size of th
a7f0: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
a800: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65  ** is also passe
a810: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72  d as a parameter
a820: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64   to both  method
a830: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  s. If the output
a840: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f   buffer.** is no
a850: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
a860: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
a870: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  ] should be retu
a880: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73  rned. Since this
a890: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61   is.** handled a
a8a0: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
a8b0: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69  by SQLite, vfs i
a8c0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
a8d0: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a  hould endeavor.*
a8e0: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  * to prevent thi
a8f0: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50  s by setting mxP
a900: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
a910: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
a920: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
a930: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
a940: 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65  xSleep(), xCurre
a950: 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43  ntTime(), and xC
a960: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
a970: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
a980: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
a990: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
a9a0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
a9b0: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
a9c0: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
a9d0: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
a9e0: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
a9f0: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
aa00: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
aa10: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
aa20: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
aa30: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
aa40: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
aa50: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
aa60: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
aa70: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
aa80: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
aa90: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
aaa0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
aab0: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
aac0: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
aad0: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
aae0: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
aaf0: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
ab00: 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78  s given.  ^The x
ab10: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
ab20: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
ab30: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
ab40: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
ab50: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
ab60: 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69  e as.** a floati
ab70: 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a  ng point value..
ab80: 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  ** ^The xCurrent
ab90: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
aba0: 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61  od returns, as a
abb0: 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a  n integer, the J
abc0: 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d  ulian.** Day Num
abd0: 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62  ber multiplied b
abe0: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20  y 86400000 (the 
abf0: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
ac00: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20  econds in .** a 
ac10: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a  24-hour day).  .
ac20: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
ac30: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74  use the xCurrent
ac40: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
ac50: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75  od to get the cu
ac60: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e  rrent.** date an
ac70: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d  d time if that m
ac80: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62  ethod is availab
ac90: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20  le (if iVersion 
aca0: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61  is 2 or .** grea
acb0: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63  ter and the func
acc0: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
acd0: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69  not NULL) and wi
ace0: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20  ll fall back.** 
acf0: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  to xCurrentTime(
ad00: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d  ) if xCurrentTim
ad10: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76  eInt64() is unav
ad20: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ailable..**.** ^
ad30: 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61  The xSetSystemCa
ad40: 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d  ll(), xGetSystem
ad50: 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73  Call(), and xNes
ad60: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e  tSystemCall() in
ad70: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20  terfaces.** are 
ad80: 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20  not used by the 
ad90: 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68  SQLite core.  Th
ada0: 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74  ese optional int
adb0: 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
adc0: 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20  ided.** by some 
add0: 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74  VFSes to facilit
ade0: 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74  ate testing of t
adf0: 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20  he VFS code. By 
ae00: 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73  overriding .** s
ae10: 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68  ystem calls with
ae20: 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72   functions under
ae30: 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20   its control, a 
ae40: 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e  test program can
ae50: 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75  .** simulate fau
ae60: 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f  lts and error co
ae70: 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f  nditions that wo
ae80: 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65  uld otherwise be
ae90: 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72   difficult.** or
aea0: 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69   impossible to i
aeb0: 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20  nduce.  The set 
aec0: 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  of system calls 
aed0: 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
aee0: 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73  ridden.** varies
aef0: 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f   from one VFS to
af00: 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72   another, and fr
af10: 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f  om one version o
af20: 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74  f the same VFS t
af30: 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20  o the.** next.  
af40: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
af50: 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65  t use these inte
af60: 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70  rfaces must be p
af70: 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a  repared for any.
af80: 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65  ** or all of the
af90: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f  se interfaces to
afa0: 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20   be NULL or for 
afb0: 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74  their behavior t
afc0: 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d  o change.** from
afd0: 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20   one release to 
afe0: 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  the next.  Appli
aff0: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74  cations must not
b000: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65   attempt to acce
b010: 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65  ss.** any of the
b020: 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68  se methods if th
b030: 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68  e iVersion of th
b040: 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68  e VFS is less th
b050: 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  an 3..*/.typedef
b060: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
b070: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
b080: 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
b090: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
b0a0: 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75  ptr)(void);.stru
b0b0: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
b0c0: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
b0d0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
b0e0: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
b0f0: 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74   number (current
b100: 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73  ly 3) */.  int s
b110: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
b120: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
b130: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
b140: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
b150: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
b160: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
b170: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
b180: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
b190: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
b1a0: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
b1b0: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
b1c0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
b1d0: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
b1e0: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
b1f0: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
b200: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
b210: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
b220: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
b230: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
b240: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
b250: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
b260: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
b270: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
b280: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
b290: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
b2a0: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
b2b0: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
b2c0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
b2d0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
b2e0: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
b2f0: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
b300: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
b310: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
b320: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
b330: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
b340: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
b350: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
b360: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
b370: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
b380: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
b390: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
b3a0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
b3b0: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
b3c0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
b3d0: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
b3e0: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
b3f0: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
b400: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
b410: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
b420: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
b430: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
b440: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
b450: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
b460: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
b470: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
b480: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
b490: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
b4a0: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
b4b0: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
b4c0: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
b4d0: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
b4e0: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
b4f0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
b500: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
b510: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
b520: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
b530: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20  char *);.  /*.  
b540: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
b550: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
b560: 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c  ion 1 of the sql
b570: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20  ite_vfs object. 
b580: 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   ** definition. 
b590: 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c   Those that foll
b5a0: 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20  ow are added in 
b5b0: 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74  version 2 or lat
b5c0: 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  er.  */.  int (*
b5d0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
b5e0: 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  4)(sqlite3_vfs*,
b5f0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29   sqlite3_int64*)
b600: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
b610: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
b620: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
b630: 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c  and 2 of the sql
b640: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
b650: 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77    ** Those below
b660: 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e   are for version
b670: 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a   3 and greater..
b680: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65    */.  int (*xSe
b690: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
b6a0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
b6b0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
b6c0: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
b6d0: 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79  r);.  sqlite3_sy
b6e0: 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74  scall_ptr (*xGet
b6f0: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
b700: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
b710: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
b720: 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e  const char *(*xN
b730: 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  extSystemCall)(s
b740: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
b750: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
b760: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
b770: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
b780: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74   in versions 1 t
b790: 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20  hrough 3 of the 
b7a0: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
b7b0: 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
b7c0: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
b7d0: 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72  ed in figure ver
b7e0: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
b7f0: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
b800: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
b810: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
b820: 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
b830: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
b840: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
b850: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
b860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
b870: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
b880: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
b890: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
b8a0: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
b8b0: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
b8c0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
b8d0: 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
b8e0: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
b8f0: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
b900: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
b910: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
b920: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
b930: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
b940: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
b950: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
b960: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
b970: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
b980: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
b990: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
b9a0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
b9b0: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
b9c0: 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
b9d0: 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
b9e0: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
b9f0: 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
ba00: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
ba10: 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
ba20: 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
ba30: 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
ba40: 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
ba50: 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
ba60: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
ba70: 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
ba80: 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
ba90: 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
baa0: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
bab0: 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
bac0: 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
bad0: 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
bae0: 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
baf0: 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
bb00: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
bb10: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
bb20: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
bb30: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
bb40: 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
bb50: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
bb60: 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
bb70: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
bb80: 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
bb90: 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
bba0: 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
bbb0: 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
bbc0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
bbd0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
bbe0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
bbf0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
bc00: 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
bc10: 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
bc20: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
bc30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
bc40: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
bc50: 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
bc60: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
bc70: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
bc80: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
bc90: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
bca0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
bcb0: 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
bcc0: 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
bcd0: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
bce0: 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
bcf0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
bd00: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
bd10: 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
bd20: 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
bd30: 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
bd40: 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
bd50: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
bd60: 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
bd70: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
bd80: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
bd90: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
bda0: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
bdb0: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
bdc0: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
bdd0: 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
bde0: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
bdf0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
be00: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
be10: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
be20: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
be30: 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
be40: 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
be50: 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
be60: 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
be70: 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
be80: 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
be90: 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f   given no the co
bea0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
beb0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
bec0: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
bed0: 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
bee0: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
bef0: 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
bf00: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
bf10: 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
bf20: 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
bf30: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
bf40: 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
bf50: 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
bf60: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
bf70: 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
bf80: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
bf90: 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
bfa0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
bfb0: 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
bfc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
bfd0: 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
bfe0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
bff0: 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
c000: 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
c010: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
c020: 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
c030: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
c040: 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
c050: 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
c060: 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
c070: 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
c080: 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
c090: 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
c0a0: 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
c0b0: 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
c0c0: 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
c0d0: 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
c0e0: 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
c0f0: 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
c100: 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
c110: 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
c120: 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
c130: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
c140: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
c150: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
c160: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
c170: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
c180: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
c190: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
c1a0: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
c1b0: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
c1c0: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
c1d0: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
c1e0: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
c1f0: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
c200: 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
c210: 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
c220: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
c230: 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
c240: 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
c250: 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
c260: 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
c270: 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
c280: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
c290: 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
c2a0: 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
c2b0: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
c2c0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
c2d0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
c2e0: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
c2f0: 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
c300: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
c310: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
c320: 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
c330: 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
c340: 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
c350: 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
c360: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
c370: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
c380: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
c390: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
c3a0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
c3b0: 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
c3c0: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
c3d0: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
c3e0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
c3f0: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
c400: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
c410: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
c420: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
c430: 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
c440: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
c450: 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
c460: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
c470: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
c480: 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
c490: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
c4a0: 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
c4b0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
c4c0: 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
c4d0: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
c4e0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
c4f0: 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
c500: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
c510: 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
c520: 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
c530: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
c540: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
c550: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
c560: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
c570: 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
c580: 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
c590: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
c5a0: 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
c5b0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
c5c0: 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
c5d0: 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
c5e0: 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
c5f0: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
c600: 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
c610: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
c620: 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
c630: 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
c640: 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
c650: 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
c660: 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
c670: 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
c680: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
c690: 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
c6a0: 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
c6b0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
c6c0: 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
c6d0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
c6e0: 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
c6f0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
c700: 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
c710: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
c720: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
c730: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
c740: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
c750: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
c760: 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
c770: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
c780: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
c790: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
c7a0: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
c7b0: 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
c7c0: 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
c7d0: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
c7e0: 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
c7f0: 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
c800: 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
c810: 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
c820: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
c830: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
c840: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
c850: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
c860: 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
c870: 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
c880: 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
c890: 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
c8a0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
c8b0: 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
c8c0: 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
c8d0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
c8e0: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
c8f0: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
c900: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
c910: 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
c920: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
c930: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
c940: 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
c950: 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
c960: 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
c970: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
c980: 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
c990: 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
c9a0: 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
c9b0: 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
c9c0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
c9d0: 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
c9e0: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
c9f0: 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
ca00: 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
ca10: 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
ca20: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
ca30: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
ca40: 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
ca50: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
ca60: 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
ca70: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
ca80: 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
ca90: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
caa0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
cab0: 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
cac0: 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
cad0: 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
cae0: 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
caf0: 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
cb00: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
cb10: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
cb20: 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
cb30: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
cb40: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
cb50: 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
cb60: 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
cb70: 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
cb80: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
cb90: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
cba0: 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
cbb0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
cbc0: 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
cbd0: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
cbe0: 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
cbf0: 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
cc00: 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
cc10: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
cc20: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
cc30: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
cc40: 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
cc50: 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
cc60: 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
cc70: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
cc80: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
cc90: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
cca0: 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
ccb0: 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
ccc0: 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
ccd0: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
cce0: 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
ccf0: 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
cd00: 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
cd10: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
cd20: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
cd30: 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
cd40: 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
cd50: 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
cd60: 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
cd70: 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
cd80: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
cd90: 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
cda0: 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
cdb0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
cdc0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
cdd0: 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
cde0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
cdf0: 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
ce00: 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
ce10: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
ce20: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
ce30: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
ce40: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
ce50: 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
ce60: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
ce70: 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
ce80: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
ce90: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
cea0: 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
ceb0: 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
cec0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
ced0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
cee0: 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
cef0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
cf00: 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
cf10: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
cf20: 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
cf30: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
cf40: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
cf50: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
cf60: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
cf70: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
cf80: 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
cf90: 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
cfa0: 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
cfb0: 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
cfc0: 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
cfd0: 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
cfe0: 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
cff0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
d000: 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
d010: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
d020: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
d030: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
d040: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
d050: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
d060: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
d070: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
d080: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
d090: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
d0a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
d0b0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
d0c0: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
d0d0: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
d0e0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
d0f0: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
d100: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
d110: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
d120: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
d130: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
d140: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
d150: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
d160: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
d170: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
d180: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
d190: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
d1a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
d1b0: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
d1c0: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
d1d0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
d1e0: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
d1f0: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
d200: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
d210: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
d220: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
d230: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
d240: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
d250: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
d260: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
d270: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
d280: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
d290: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
d2a0: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
d2b0: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
d2c0: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
d2d0: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
d2e0: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
d2f0: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
d300: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
d310: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
d320: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  needs..**.** The
d330: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
d340: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
d350: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  ot threadsafe.  
d360: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
d370: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  ** must insure t
d380: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
d390: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
d3a0: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
d3b0: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
d3c0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
d3d0: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
d3e0: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20  .  Furthermore, 
d3f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
d400: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
d410: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
d420: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
d430: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
d440: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
d450: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
d460: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
d470: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
d480: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
d490: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
d4a0: 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
d4b0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d4c0: 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
d4d0: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
d4e0: 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
d4f0: 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
d500: 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
d510: 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
d520: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
d530: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
d540: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
d550: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
d560: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
d570: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
d580: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
d590: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
d5a0: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
d5b0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
d5c0: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f  n integer.** [co
d5d0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
d5e0: 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69  on] that determi
d5f0: 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70  nes.** what prop
d600: 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69  erty of SQLite i
d610: 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72  s to be configur
d620: 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  ed.  Subsequent 
d630: 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72  arguments.** var
d640: 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
d650: 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  he [configuratio
d660: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
d670: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
d680: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
d690: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
d6a0: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
d6b0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
d6c0: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
d6d0: 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
d6e0: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
d6f0: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
d700: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
d710: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
d720: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
d730: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
d740: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
d750: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  .int sqlite3_con
d760: 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a  fig(int, ...);..
d770: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
d780: 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61  Configure databa
d790: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
d7a0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
d7b0: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
d7c0: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
d7d0: 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61  o make configura
d7e0: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
d7f0: 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  to a [database c
d800: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
d810: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69   interface is si
d820: 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  milar to.** [sql
d830: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65  ite3_config()] e
d840: 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63  xcept that the c
d850: 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20  hanges apply to 
d860: 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74  a single.** [dat
d870: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d880: 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20  ] (specified in 
d890: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
d8a0: 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  nt)..**.** The s
d8b0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
d8c0: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
d8d0: 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73  fig(D,V,...)  is
d8e0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
d8f0: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
d900: 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  DE | configurati
d910: 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e  on verb] - an in
d920: 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74  teger code .** t
d930: 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68  hat indicates wh
d940: 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  at aspect of the
d950: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
d960: 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
d970: 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53  configured..** S
d980: 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
d990: 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69  nts vary dependi
d9a0: 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67  ng on the config
d9b0: 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a  uration verb..**
d9c0: 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71  .** ^Calls to sq
d9d0: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
d9e0: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
d9f0: 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  OK if and only i
da00: 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73  f.** the call is
da10: 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63   considered succ
da20: 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  essful..*/.int s
da30: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
da40: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
da50: 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  p, ...);../*.** 
da60: 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
da70: 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74   Allocation Rout
da80: 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ines.**.** An in
da90: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
daa0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
dab0: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
dac0: 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e  een SQLite.** an
dad0: 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  d low-level memo
dae0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
daf0: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
db00: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  is object is use
db10: 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c  d in only one pl
db20: 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74  ace in the SQLit
db30: 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
db40: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
db50: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
db60: 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61   object is the a
db70: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73  rgument to.** [s
db80: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
db90: 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67   when the config
dba0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
dbb0: 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  s.** [SQLITE_CON
dbc0: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b  FIG_MALLOC] or [
dbd0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
dbe0: 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42  TMALLOC].  .** B
dbf0: 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e  y creating an in
dc00: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
dc10: 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73  bject.** and pas
dc20: 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
dc30: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
dc40: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
dc50: 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f  C]).** during co
dc60: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20  nfiguration, an 
dc70: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20  application can 
dc80: 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
dc90: 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
dca0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
dcb0: 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65  ystem for SQLite
dcc0: 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20   to use for all 
dcd0: 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69  of its.** dynami
dce0: 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a  c memory needs..
dcf0: 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
dd00: 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74  SQLite comes wit
dd10: 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74  h several [built
dd20: 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
dd30: 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61  ators].** that a
dd40: 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65  re perfectly ade
dd50: 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76  quate for the ov
dd60: 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72  erwhelming major
dd70: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
dd80: 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ons.** and that 
dd90: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f  this object is o
dda0: 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20  nly useful to a 
ddb0: 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66  tiny minority of
ddc0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
ddd0: 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65   with specialize
dde0: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
ddf0: 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73  ion requirements
de00: 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  .  This object i
de10: 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64  s.** also used d
de20: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66  uring testing of
de30: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
de40: 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61   to specify an a
de50: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
de60: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74  mory allocator t
de70: 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65  hat simulates me
de80: 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f  mory out-of-memo
de90: 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e  ry conditions in
dea0: 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72  .** order to ver
deb0: 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20  ify that SQLite 
dec0: 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75  recovers gracefu
ded0: 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a  lly from such.**
dee0: 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a   conditions..**.
def0: 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20  ** The xMalloc, 
df00: 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46  xRealloc, and xF
df10: 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74  ree methods must
df20: 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a   work like the.*
df30: 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c  * malloc(), real
df40: 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
df50: 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20   functions from 
df60: 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
df70: 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  ibrary..** ^SQLi
df80: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
df90: 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  at the second ar
dfa0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65  gument to.** xRe
dfb0: 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20  alloc is always 
dfc0: 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  a value returned
dfd0: 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c   by a prior call
dfe0: 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a   to xRoundup..**
dff0: 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64  .** xSize should
e000: 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f   return the allo
e010: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20  cated size of a 
e020: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
e030: 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  n.** previously 
e040: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d  obtained from xM
e050: 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f  alloc or xReallo
e060: 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65  c.  The allocate
e070: 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77  d size.** is alw
e080: 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20  ays at least as 
e090: 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65  big as the reque
e0a0: 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61  sted size but ma
e0b0: 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a  y be larger..**.
e0c0: 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20  ** The xRoundup 
e0d0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77  method returns w
e0e0: 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65  hat would be the
e0f0: 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
e100: 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61  of.** a memory a
e110: 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20  llocation given 
e120: 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71  a particular req
e130: 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f  uested size.  Mo
e140: 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  st memory.** all
e150: 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
e160: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
e170: 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20  ons at least to 
e180: 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c  the next multipl
e190: 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65  e.** of 8.  Some
e1a0: 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
e1b0: 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72  d up to a larger
e1c0: 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20   multiple or to 
e1d0: 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a  a power of 2..**
e1e0: 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c   Every memory al
e1f0: 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74  location request
e200: 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75   coming in throu
e210: 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  gh [sqlite3_mall
e220: 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  oc()].** or [sql
e230: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
e240: 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75  first calls xRou
e250: 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64  ndup.  If xRound
e260: 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a  up returns 0, .*
e270: 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68  * that causes th
e280: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
e290: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
e2a0: 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a  n to fail..**.**
e2b0: 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   The xInit metho
e2c0: 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  d initializes th
e2d0: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
e2e0: 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c  or.  (For exampl
e2f0: 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61  e,.** it might a
e300: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75  llocate any requ
e310: 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69  ire mutexes or i
e320: 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e  nitialize intern
e330: 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63  al data.** struc
e340: 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75  tures.  The xShu
e350: 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
e360: 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63  invoked (indirec
e370: 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  tly) by.** [sqli
e380: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
e390: 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c  and should deall
e3a0: 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72  ocate any resour
e3b0: 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20  ces acquired.** 
e3c0: 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70  by xInit.  The p
e3d0: 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20  AppData pointer 
e3e0: 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f  is used as the o
e3f0: 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
e400: 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53  .** xInit and xS
e410: 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53  hutdown..**.** S
e420: 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20  QLite holds the 
e430: 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
e440: 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74  ATIC_MASTER] mut
e450: 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b  ex when it invok
e460: 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20  es.** the xInit 
e470: 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78  method, so the x
e480: 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64  Init method need
e490: 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61   not be threadsa
e4a0: 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75  fe.  The.** xShu
e4b0: 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
e4c0: 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d  only called from
e4d0: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
e4e0: 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73  wn()] so it does
e4f0: 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  .** not need to 
e500: 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69  be threadsafe ei
e510: 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f  ther.  For all o
e520: 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51  ther methods, SQ
e530: 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68  Lite.** holds th
e540: 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
e550: 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65  STATIC_MEM] mute
e560: 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  x as long as the
e570: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
e580: 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f  IG_MEMSTATUS] co
e590: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
e5a0: 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20  on is turned on 
e5b0: 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20  (which.** it is 
e5c0: 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20  by default) and 
e5d0: 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61  so the methods a
e5e0: 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
e5f0: 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20   serialized..** 
e600: 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c  However, if [SQL
e610: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
e620: 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65  ATUS] is disable
e630: 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65  d, then the othe
e640: 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73  r.** methods mus
e650: 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  t be threadsafe 
e660: 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65  or else make the
e670: 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65  ir own arrangeme
e680: 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61  nts for.** seria
e690: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  lization..**.** 
e6a0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
e6b0: 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29  r invoke xInit()
e6c0: 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20   more than once 
e6d0: 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72  without an inter
e6e0: 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74  vening.** call t
e6f0: 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  o xShutdown()..*
e700: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
e710: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
e720: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d  hods sqlite3_mem
e730: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
e740: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
e750: 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28  hods {.  void *(
e760: 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20  *xMalloc)(int); 
e770: 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72          /* Memor
e780: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e  y allocation fun
e790: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
e7a0: 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b  (*xFree)(void*);
e7b0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65            /* Fre
e7c0: 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  e a prior alloca
e7d0: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
e7e0: 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64  (*xRealloc)(void
e7f0: 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69  *,int);  /* Resi
e800: 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze an allocation
e810: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a   */.  int (*xSiz
e820: 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
e830: 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74       /* Return t
e840: 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c  he size of an al
e850: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
e860: 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e  t (*xRoundup)(in
e870: 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t);          /* 
e880: 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74  Round up request
e890: 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74   size to allocat
e8a0: 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e  ion size */.  in
e8b0: 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a  t (*xInit)(void*
e8c0: 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
e8d0: 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  Initialize the m
e8e0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
e8f0: 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75  */.  void (*xShu
e900: 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20  tdown)(void*);  
e910: 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c      /* Deinitial
e920: 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
e930: 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
e940: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
e950: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
e960: 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69  Argument to xIni
e970: 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77  t() and xShutdow
e980: 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  n() */.};../*.**
e990: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
e9a0: 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
e9b0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
e9c0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
e9d0: 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion}.**.** These
e9e0: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
e9f0: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
ea00: 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
ea10: 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
ea20: 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
ea30: 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
ea40: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
ea50: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
ea60: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
ea70: 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
ea80: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
ea90: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
eaa0: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
eab0: 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
eac0: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
ead0: 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
eae0: 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
eaf0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
eb00: 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
eb10: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
eb20: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  om [sqlite3_conf
eb30: 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
eb40: 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
eb50: 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65  all worked.  The
eb60: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
eb70: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
eb80: 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
eb90: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
eba0: 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
ebb0: 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
ebc0: 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
ebd0: 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
ebe0: 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
ebf0: 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
ec00: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
ec10: 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
ec20: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
ec30: 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
ec40: 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
ec50: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
ec60: 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
ec70: 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
ec80: 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
ec90: 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68  de] to Single-th
eca0: 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
ecb0: 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
ecc0: 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69  es.** all mutexi
ecd0: 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69  ng and puts SQLi
ece0: 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77  te into a mode w
ecf0: 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79  here it can only
ed00: 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61   be used.** by a
ed10: 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
ed20: 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
ed30: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
ed40: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
ed50: 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
ed60: 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
ed70: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
ed80: 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
ed90: 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
eda0: 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72   change the [thr
edb0: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f  eading mode] fro
edc0: 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a  m its default.**
edd0: 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65   value of Single
ede0: 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b  -thread and so [
edf0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ee00: 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a  ] will return .*
ee10: 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
ee20: 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
ee30: 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
ee40: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a  G_SINGLETHREAD.*
ee50: 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
ee60: 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
ee70: 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
ee80: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d  IG_MULTITHREAD]]
ee90: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
eea0: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f  IG_MULTITHREAD</
eeb0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
eec0: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
eed0: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
eee0: 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
eef0: 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
ef00: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
ef10: 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49  Multi-thread.  I
ef20: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
ef30: 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  t disables.** mu
ef40: 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
ef50: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
ef60: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
ef70: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
ef80: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
ef90: 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
efa0: 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
efb0: 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
efc0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
efd0: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
efe0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
eff0: 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
f000: 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
f010: 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
f020: 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
f030: 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
f040: 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
f050: 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f  nvironment as lo
f060: 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72  ng as no two thr
f070: 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20  eads attempt to 
f080: 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
f090: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
f0a0: 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d  tion] at the sam
f0b0: 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c  e time.  ^If SQL
f0c0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
f0d0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
f0e0: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
f0f0: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
f100: 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
f110: 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
f120: 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
f130: 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
f140: 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  Multi-thread [th
f150: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
f160: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
f170: 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
f180: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
f190: 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
f1a0: 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
f1b0: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
f1c0: 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  AD configuration
f1d0: 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
f1e0: 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
f1f0: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d  FIG_SERIALIZED]]
f200: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
f210: 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64  IG_SERIALIZED</d
f220: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
f230: 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
f240: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
f250: 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
f260: 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
f270: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
f280: 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74  erialized. In ot
f290: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20  her words, this 
f2a0: 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a  option enables.*
f2b0: 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e  * all mutexes in
f2c0: 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75  cluding the recu
f2d0: 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73  rsive.** mutexes
f2e0: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
f2f0: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
f300: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
f310: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49  t] objects..** I
f320: 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69  n this mode (whi
f330: 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
f340: 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  t when SQLite is
f350: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
f360: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
f370: 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c  SAFE=1]) the SQL
f380: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
f390: 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a   itself serializ
f3a0: 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b  e access.** to [
f3b0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f3c0: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
f3d0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
f3e0: 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61  so that the.** a
f3f0: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72  pplication is fr
f400: 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  ee to use the sa
f410: 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
f420: 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a  nection] or the.
f430: 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  ** same [prepare
f440: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
f450: 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
f460: 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  s at the same ti
f470: 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  me..** ^If SQLit
f480: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
f490: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
f4a0: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
f4b0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
f4c0: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
f4d0: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
f4e0: 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
f4f0: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65  le to set the Se
f500: 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
f510: 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
f520: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
f530: 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
f540: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
f550: 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
f560: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
f570: 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f  IG_SERIALIZED co
f580: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
f590: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
f5a0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
f5b0: 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
f5c0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
f5d0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
f5e0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
f5f0: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
f600: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
f610: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
f620: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
f630: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
f640: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
f650: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
f660: 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
f670: 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
f680: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
f690: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
f6a0: 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
f6b0: 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
f6c0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
f6d0: 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
f6e0: 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69   SQLite.)^ ^SQLi
f6f0: 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20  te makes.** its 
f700: 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
f710: 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
f720: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
f730: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
f740: 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65  ucture.** before
f750: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
f760: 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74  nfig()] call ret
f770: 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  urns.</dd>.**.**
f780: 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
f790: 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  _GETMALLOC]] <dt
f7a0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
f7b0: 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
f7c0: 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
f7d0: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
f7e0: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
f7f0: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
f800: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
f810: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
f820: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
f830: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73  ructure.  The [s
f840: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
f850: 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
f860: 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
f870: 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
f880: 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  fined memory all
f890: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
f8a0: 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
f8b0: 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
f8c0: 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
f8d0: 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
f8e0: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
f8f0: 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
f900: 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  per that simulat
f910: 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ions memory allo
f920: 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f  cation failure o
f930: 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f  r.** tracks memo
f940: 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78  ry usage, for ex
f950: 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ample. </dd>.**.
f960: 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
f970: 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c  IG_MEMSTATUS]] <
f980: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
f990: 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a  _MEMSTATUS</dt>.
f9a0: 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
f9b0: 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
f9c0: 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
f9d0: 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65  pe int, interpre
f9e0: 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f  ted as a .** boo
f9f0: 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
fa00: 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
fa10: 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
fa20: 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
fa30: 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69  ion .** statisti
fa40: 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72  cs. ^(When memor
fa50: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
fa60: 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
fa70: 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f  bled, the .** fo
fa80: 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69  llowing SQLite i
fa90: 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65  nterfaces become
faa0: 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
fab0: 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
fac0: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
fad0: 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
fae0: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
faf0: 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
fb00: 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
fb10: 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
fb20: 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20  p_limit64()].** 
fb30: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
fb40: 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c  status()].**   <
fb50: 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
fb60: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
fb70: 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
fb80: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
fb90: 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
fba0: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
fbb0: 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
fbc0: 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
fbd0: 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
fbe0: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
fbf0: 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
fc00: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
fc10: 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
fc20: 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
fc30: 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64  FIG_SCRATCH]] <d
fc40: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
fc50: 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
fc60: 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
fc70: 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
fc80: 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
fc90: 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
fca0: 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63  an use for.** sc
fcb0: 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54  ratch memory.  T
fcc0: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
fcd0: 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69  rguments:  A poi
fce0: 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a  nter an 8-byte.*
fcf0: 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  * aligned memory
fd00: 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69   buffer from whi
fd10: 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61  ch the scratch a
fd20: 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20  llocations will 
fd30: 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65  be.** drawn, the
fd40: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63   size of each sc
fd50: 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
fd60: 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68   (sz),.** and th
fd70: 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
fd80: 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f   of scratch allo
fd90: 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68  cations (N).  Th
fda0: 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  e sz.** argument
fdb0: 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69   must be a multi
fdc0: 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68  ple of 16..** Th
fdd0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
fde0: 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74   must be a point
fdf0: 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  er to an 8-byte 
fe00: 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a  aligned buffer.*
fe10: 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  * of at least sz
fe20: 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
fe30: 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
fe40: 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20  ill use no more 
fe50: 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68  than two scratch
fe60: 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72   buffers per thr
fe70: 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68  ead.  So.** N sh
fe80: 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74  ould be set to t
fe90: 77 69 63 65 20 74 68 65 20 65 78 70 65 63 74 65  wice the expecte
fea0: 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  d maximum number
feb0: 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20   of threads..** 
fec0: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76  ^SQLite will nev
fed0: 65 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72  er require a scr
fee0: 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74  atch buffer that
fef0: 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a   is more than 6.
ff00: 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74  ** times the dat
ff10: 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e  abase page size.
ff20: 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64   ^If SQLite need
ff30: 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e  s needs addition
ff40: 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65  al.** scratch me
ff50: 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74  mory beyond what
ff60: 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
ff70: 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  this configurati
ff80: 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  on option, then 
ff90: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
ffa0: 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75  loc()] will be u
ffb0: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
ffc0: 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e  e memory needed.
ffd0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
ffe0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
fff0: 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CACHE]] <dt>SQLI
10000 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
10010 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
10020 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
10030 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
10040 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
10050 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
10060 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61  se for.** the da
10070 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68  tabase page cach
10080 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75  e with the defau
10090 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  lt page cache im
100a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a  plementation.  .
100b0 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
100c0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
100d0 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61   be used if an a
100e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
100f0 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
10100 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
10110 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
10120 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
10130 5f 50 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a  _PCACHE option..
10140 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
10150 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
10160 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70  this option: A p
10170 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65  ointer to 8-byte
10180 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f   aligned.** memo
10190 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ry, the size of 
101a0 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72  each page buffer
101b0 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e   (sz), and the n
101c0 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28  umber of pages (
101d0 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72  N)..** The sz ar
101e0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
101f0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
10200 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73   largest databas
10210 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77  e page.** (a pow
10220 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65  er of two betwee
10230 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 29  n 512 and 32768)
10240 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65   plus a little e
10250 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a  xtra for each.**
10260 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e   page header.  ^
10270 54 68 65 20 70 61 67 65 20 68 65 61 64 65 72 20  The page header 
10280 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30  size is 20 to 40
10290 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67   bytes depending
102a0 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20   on.** the host 
102b0 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e  architecture.  ^
102c0 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20  It is harmless, 
102d0 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77  apart from the w
102e0 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  asted memory,.**
102f0 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69   to make sz a li
10300 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20  ttle too large. 
10310 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72   The first.** ar
10320 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f  gument should po
10330 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61  int to an alloca
10340 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74  tion of at least
10350 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
10360 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
10370 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d  e will use the m
10380 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62  emory provided b
10390 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  y the first argu
103a0 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20  ment to satisfy 
103b0 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65  its.** memory ne
103c0 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73  eds for the firs
103d0 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69  t N pages that i
103e0 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e  t adds to cache.
103f0 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c    ^If additional
10400 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d  .** page cache m
10410 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20  emory is needed 
10420 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
10430 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
10440 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20  option, then.** 
10450 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b  SQLite goes to [
10460 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
10470 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69  ] for the additi
10480 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61  onal storage spa
10490 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  ce..** The point
104a0 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
104b0 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a  argument must.**
104c0 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
104d0 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
104e0 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
104f0 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
10500 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e  te.** will be un
10510 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a  defined.</dd>.**
10520 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
10530 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53  FIG_HEAP]] <dt>S
10540 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
10550 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  P</dt>.** <dd> ^
10560 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
10570 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
10580 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
10590 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  t SQLite will us
105a0 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20  e.** for all of 
105b0 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
105c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
105d0 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65  eds beyond those
105e0 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72   provided.** for
105f0 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   by [SQLITE_CONF
10600 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20  IG_SCRATCH] and 
10610 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
10620 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68  AGECACHE]..** Th
10630 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
10640 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79  guments: An 8-by
10650 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74  te aligned point
10660 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  er to the memory
10670 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  ,.** the number 
10680 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
10690 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61  memory buffer, a
106a0 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  nd the minimum a
106b0 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a  llocation size..
106c0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74  ** ^If the first
106d0 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
106e0 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73  mory pointer) is
106f0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69   NULL, then SQLi
10700 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f  te reverts.** to
10710 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75   using its defau
10720 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
10730 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20  tor (the system 
10740 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65  malloc() impleme
10750 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64  ntation),.** und
10760 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69  oing any prior i
10770 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51  nvocation of [SQ
10780 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
10790 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  OC].  ^If the.**
107a0 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20   memory pointer 
107b0 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20  is not NULL and 
107c0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45  either [SQLITE_E
107d0 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f  NABLE_MEMSYS3] o
107e0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  r.** [SQLITE_ENA
107f0 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65  BLE_MEMSYS5] are
10800 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74   defined, then t
10810 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d  he alternative m
10820 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
10830 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f  or is engaged to
10840 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53   handle all of S
10850 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c  QLites memory al
10860 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a  location needs..
10870 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69  ** The first poi
10880 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
10890 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62   pointer) must b
108a0 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
108b0 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61  8-byte.** bounda
108c0 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
108d0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
108e0 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  ite will be unde
108f0 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69  fined..** The mi
10900 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
10910 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20   size is capped 
10920 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e  at 2**12. Reason
10930 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66  able values.** f
10940 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  or the minimum a
10950 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61  llocation size a
10960 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20  re 2**5 through 
10970 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  2**8.</dd>.**.**
10980 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
10990 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  _MUTEX]] <dt>SQL
109a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
109b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
109c0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
109d0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
109e0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
109f0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
10a00 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
10a10 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
10a20 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
10a30 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
10a40 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
10a50 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
10a60 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  vel mutex routin
10a70 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e  es to be used in
10a80 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75   place.** the mu
10a90 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69  tex routines bui
10aa0 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
10ab0 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
10ac0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
10ad0 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  * content of the
10ae0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
10af0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
10b00 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61  re before the ca
10b10 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
10b20 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75  3_config()] retu
10b30 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  rns. ^If SQLite 
10b40 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
10b50 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
10b60 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
10b70 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
10b80 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
10b90 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
10ba0 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
10bb0 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
10bc0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
10bd0 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
10be0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
10bf0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
10c00 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
10c10 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66  ONFIG_MUTEX conf
10c20 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10c30 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
10c40 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
10c50 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
10c60 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
10c70 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TEX]] <dt>SQLITE
10c80 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
10c90 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
10ca0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
10cb0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
10cc0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
10cd0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
10ce0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
10cf0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
10d00 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
10d10 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
10d20 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
10d30 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
10d40 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
10d50 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
10d60 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69  ined mutex routi
10d70 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
10d80 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
10d90 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
10da0 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
10db0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
10dc0 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
10dd0 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72  apper used to tr
10de0 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20  ack mutex usage 
10df0 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a  for performance.
10e00 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20  ** profiling or 
10e10 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61  testing, for exa
10e20 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69  mple.   ^If SQLi
10e30 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
10e40 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
10e50 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
10e60 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
10e70 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
10e80 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
10e90 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
10ea0 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
10eb0 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
10ec0 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
10ed0 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
10ee0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10ef0 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
10f00 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
10f10 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
10f20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
10f30 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
10f40 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
10f50 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
10f60 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74  _LOOKASIDE]] <dt
10f70 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
10f80 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
10f90 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
10fa0 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
10fb0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
10fc0 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75  ermine the defau
10fd0 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt.** memory all
10fe0 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  ocation for the 
10ff0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
11000 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61   allocator on ea
11010 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
11020 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68  connection].  Th
11030 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
11040 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
11050 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
11060 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e  e buffer slot an
11070 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20  d the second is 
11080 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
11090 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64   slots allocated
110a0 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
110b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20  e connection.)^ 
110c0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73   ^(This option s
110d0 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65  ets the.** <i>de
110e0 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73  fault</i> lookas
110f0 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53  ide size. The [S
11100 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
11110 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72  OOKASIDE].** ver
11120 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  b to [sqlite3_db
11130 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62  _config()] can b
11140 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65  e used to change
11150 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a   the lookaside.*
11160 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
11170 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f  on individual co
11180 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64  nnections.)^ </d
11190 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
111a0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d  E_CONFIG_PCACHE]
111b0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
111c0 46 49 47 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a  FIG_PCACHE</dt>.
111d0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
111e0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
111f0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
11200 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
11210 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74   to.** an [sqlit
11220 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
11230 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73  s] object.  This
11240 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
11250 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
11260 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70  ** to a custom p
11270 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
11280 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51  entation.)^  ^SQ
11290 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
112a0 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65  y of the.** obje
112b0 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 66  ct and uses it f
112c0 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  or page cache me
112d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
112e0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
112f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
11300 50 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c  PCACHE]] <dt>SQL
11310 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
11320 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
11330 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
11340 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
11350 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
11360 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
11370 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  .** [sqlite3_pca
11380 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  che_methods] obj
11390 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70  ect.  SQLite cop
113a0 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65  ies of the curre
113b0 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  nt.** page cache
113c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
113d0 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74  into that object
113e0 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
113f0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11400 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOG]] <dt>SQLITE
11410 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e  _CONFIG_LOG</dt>
11420 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
11430 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
11440 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
11450 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f   arguments: a po
11460 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75  inter to a.** fu
11470 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61  nction with a ca
11480 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20  ll signature of 
11490 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e  void(*)(void*,in
114a0 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  t,const char*), 
114b0 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65  .** and a pointe
114c0 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74  r to void. ^If t
114d0 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  he function poin
114e0 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ter is not NULL,
114f0 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65   it is.** invoke
11500 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  d by [sqlite3_lo
11510 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20  g()] to process 
11520 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65  each logging eve
11530 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
11540 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
11550 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73   is NULL, the [s
11560 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e  qlite3_log()] in
11570 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20  terface becomes 
11580 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65  a no-op..** ^The
11590 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68   void pointer th
115a0 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64  at is the second
115b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c   argument to SQL
115c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69  ITE_CONFIG_LOG i
115d0 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f  s.** passed thro
115e0 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
115f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
11600 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
11610 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
11620 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65  function wheneve
11630 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20  r that function 
11640 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68  is invoked.  ^Th
11650 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
11660 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67  er to.** the log
11670 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ger function is 
11680 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69  a copy of the fi
11690 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
116a0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
116b0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  ng.** [sqlite3_l
116c0 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69  og()] call and i
116d0 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65  s intended to be
116e0 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d   a [result code]
116f0 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e   or an.** [exten
11700 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
11710 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  .  ^The third pa
11720 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74  rameter passed t
11730 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a  o the logger is.
11740 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61  ** log message a
11750 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20  fter formatting 
11760 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  via [sqlite3_snp
11770 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65  rintf()]..** The
11780 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20   SQLite logging 
11790 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
117a0 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20   reentrant; the 
117b0 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a  logger function.
117c0 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74  ** supplied by t
117d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
117e0 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61  ust not invoke a
117f0 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
11800 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c  ace..** In a mul
11810 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c  ti-threaded appl
11820 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70  ication, the app
11830 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
11840 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
11850 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65  ion must be thre
11860 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  adsafe. </dd>.**
11870 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
11880 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51  FIG_URI]] <dt>SQ
11890 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a  LITE_CONFIG_URI.
118a0 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f 70 74  ** <dd> This opt
118b0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
118c0 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
118d0 79 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d  ype int. If non-
118e0 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52  zero, then.** UR
118f0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
11900 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20  obally enabled. 
11910 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
11920 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55   is zero, then U
11930 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69  RI handling.** i
11940 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
11950 6c 65 64 2e 20 49 66 20 55 52 49 20 68 61 6e 64  led. If URI hand
11960 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
11970 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69   enabled, all fi
11980 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65  lenames.** passe
11990 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d to [sqlite3_op
119a0 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
119b0 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  open_v2()], [sql
119c0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f  ite3_open16()] o
119d0 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61  r.** specified a
119e0 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43  s part of [ATTAC
119f0 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20  H] commands are 
11a00 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
11a10 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a  RIs, regardless.
11a20 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ** of whether or
11a30 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45   not the [SQLITE
11a40 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
11a50 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  is set when the 
11a60 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
11a70 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
11a80 2e 20 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61  . If it is globa
11a90 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69  lly disabled, fi
11aa0 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f  lenames are.** o
11ab0 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20  nly interpreted 
11ac0 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53  as URIs if the S
11ad0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66  QLITE_OPEN_URI f
11ae0 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
11af0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
11b00 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
11b10 65 6e 65 64 2e 20 42 79 20 64 65 66 61 75 6c 74  ened. By default
11b20 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  , URI handling i
11b30 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69  s globally.** di
11b40 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61  sabled. The defa
11b50 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65  ult value may be
11b60 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70   changed by comp
11b70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a  iling with the.*
11b80 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  * [SQLITE_USE_UR
11b90 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  I] symbol define
11ba0 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  d..** </dl>.*/.#
11bb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
11bc0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
11bd0 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a  D  1  /* nil */.
11be0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
11bf0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
11c00 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f  D   2  /* nil */
11c10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11c20 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
11c30 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a  D    3  /* nil *
11c40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
11c50 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20  _CONFIG_MALLOC  
11c60 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
11c70 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
11c80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
11c90 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
11ca0 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71  LOC     5  /* sq
11cb0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
11cc0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
11cd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
11ce0 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20  TCH       6  /* 
11cf0 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
11d00 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
11d10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
11d20 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f  GECACHE     7  /
11d30 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
11d40 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
11d50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
11d60 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20  HEAP          8 
11d70 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e   /* void*, int n
11d80 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f  Byte, int min */
11d90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11da0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
11db0 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65       9  /* boole
11dc0 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  an */.#define SQ
11dd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
11de0 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20  X        10  /* 
11df0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
11e00 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
11e10 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
11e20 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20  GETMUTEX     11 
11e30 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
11e40 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a  x_methods* */./*
11e50 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49   previously SQLI
11e60 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41  TE_CONFIG_CHUNKA
11e70 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73  LLOC 12 which is
11e80 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20   now unused. */ 
11e90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11ea0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
11eb0 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69      13  /* int i
11ec0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
11ed0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
11ee0 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20  HE       14  /* 
11ef0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
11f00 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
11f10 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
11f20 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
11f30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
11f40 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  che_methods* */.
11f50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
11f60 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20  ONFIG_LOG       
11f70 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c     16  /* xFunc,
11f80 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
11f90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
11fa0 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20  URI          17 
11fb0 20 2f 2a 20 69 6e 74 20 2a 2f 0a 0a 2f 2a 0a 2a   /* int */../*.*
11fc0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
11fd0 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
11fe0 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
11ff0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
12000 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
12010 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
12020 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
12030 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
12040 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
12050 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
12060 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
12070 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
12080 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
12090 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
120a0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
120b0 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
120c0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
120d0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
120e0 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
120f0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
12100 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
12110 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
12120 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
12130 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
12140 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
12150 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
12160 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
12170 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
12180 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  ed.  ^The [sqlit
12190 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
121a0 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
121b0 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
121c0 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
121d0 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
121e0 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
121f0 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
12200 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
12210 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
12220 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
12230 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
12240 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
12250 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
12260 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
12270 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
12280 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
12290 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
122a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
122b0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
122c0 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
122d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
122e0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
122f0 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
12300 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
12310 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
12320 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
12330 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62  er to a memory b
12340 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
12350 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
12360 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  y..** ^The first
12370 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20   argument after 
12380 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
12390 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65  FIG_LOOKASIDE ve
123a0 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rb.** may be NUL
123b0 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
123c0 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
123d0 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b  cate the.** look
123e0 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73  aside buffer its
123f0 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
12400 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54  e3_malloc()]. ^T
12410 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
12420 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
12430 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
12440 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e  ide buffer slot.
12450 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67    ^The third arg
12460 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
12470 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
12480 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
12490 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
124a0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
124b0 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
124c0 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
124d0 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
124e0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
124f0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
12500 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a  .  The buffer.**
12510 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
12520 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
12530 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65  undary.  ^If the
12540 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
12550 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42   to.** SQLITE_DB
12560 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
12570 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70   is not a multip
12580 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69  le of 8, it is i
12590 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75  nternally.** rou
125a0 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65  nded down to the
125b0 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75   next smaller mu
125c0 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28  ltiple of 8.  ^(
125d0 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  The lookaside me
125e0 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  mory.** configur
125f0 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61  ation for a data
12600 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
12610 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e  can only be chan
12620 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a  ged when that.**
12630 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e   connection is n
12640 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69  ot currently usi
12650 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  ng lookaside mem
12660 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72  ory, or in other
12670 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74   words.** when t
12680 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75  he "current valu
12690 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  e" returned by.*
126a0 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74  * [sqlite3_db_st
126b0 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  atus](D,[SQLITE_
126c0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
126d0 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a  ],...) is zero..
126e0 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
126f0 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
12700 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f  kaside memory co
12710 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e  nfiguration when
12720 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65   lookaside.** me
12730 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c  mory is in use l
12740 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67  eaves the config
12750 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65  uration unchange
12760 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a  d and returns .*
12770 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
12780 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  )^</dd>.**.** <d
12790 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
127a0 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64  G_ENABLE_FKEY</d
127b0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
127c0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
127d0 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
127e0 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65  able the enforce
127f0 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65  ment of.** [fore
12800 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
12810 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f  nts].  There sho
12820 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
12830 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
12840 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
12850 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
12860 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
12870 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e  to disable FK en
12880 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f  forcement,.** po
12890 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
128a0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
128b0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
128c0 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  eave FK enforcem
128d0 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ent.** unchanged
128e0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
128f0 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
12900 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
12910 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
12920 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
12930 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
12940 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63  hether FK enforc
12950 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20  ement is off or 
12960 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  on.** following 
12970 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
12980 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
12990 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
129a0 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
129b0 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20  ich case the FK 
129c0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74  enforcement sett
129d0 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
129e0 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
129f0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
12a00 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
12a10 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a  _TRIGGER</dt>.**
12a20 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
12a30 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
12a40 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
12a50 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
12a60 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20  | triggers]..** 
12a70 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
12a80 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
12a90 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
12aa0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
12ab0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
12ac0 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
12ad0 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a  ble triggers,.**
12ae0 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
12af0 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20  ble triggers or 
12b00 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
12b10 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e  e the setting un
12b20 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
12b30 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
12b40 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
12b50 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
12b60 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
12b70 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
12b80 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
12b90 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73  triggers are dis
12ba0 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
12bb0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
12bc0 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
12bd0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
12be0 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
12bf0 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
12c00 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67  h case the trigg
12c10 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  er setting is no
12c20 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
12c30 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64   </dd>.**.** </d
12c40 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
12c50 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
12c60 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30  OKASIDE       10
12c70 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  01  /* void* int
12c80 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
12c90 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
12ca0 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20  ENABLE_FKEY     
12cb0 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74  1002  /* int int
12cc0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
12cd0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
12ce0 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30  BLE_TRIGGER  100
12cf0 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  3  /* int int* *
12d00 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  /.../*.** CAPI3R
12d10 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
12d20 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
12d30 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a  esult Codes.**.*
12d40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
12d50 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
12d60 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
12d70 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
12d80 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
12d90 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
12da0 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
12db0 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64  ite. ^The extend
12dc0 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
12dd0 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
12de0 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
12df0 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
12e00 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20  ibility..*/.int 
12e10 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
12e20 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71  _result_codes(sq
12e30 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66  lite3*, int onof
12e40 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
12e50 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74  REF: Last Insert
12e60 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61   Rowid.**.** ^Ea
12e70 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53  ch entry in an S
12e80 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20  QLite table has 
12e90 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20  a unique 64-bit 
12ea0 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65  signed.** intege
12eb0 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65  r key called the
12ec0 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64   [ROWID | "rowid
12ed0 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69  "]. ^The rowid i
12ee0 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62  s always availab
12ef0 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65  le.** as an unde
12f00 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61  clared column na
12f10 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20  med ROWID, OID, 
12f20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f  or _ROWID_ as lo
12f30 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e  ng as those.** n
12f40 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73  ames are not als
12f50 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63  o used by explic
12f60 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
12f70 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68  lumns. ^If.** th
12f80 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f  e table has a co
12f90 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e  lumn of type [IN
12fa0 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
12fb0 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c  Y] then that col
12fc0 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65  umn.** is anothe
12fd0 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20  r alias for the 
12fe0 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rowid..**.** ^Th
12ff0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
13000 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  ns the [rowid] o
13010 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
13020 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  t.** successful 
13030 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68  [INSERT] into th
13040 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20  e database from 
13050 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
13060 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  nnection].** in 
13070 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
13080 6e 74 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c 69  nt.  ^As of SQLi
13090 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37  te version 3.7.7
130a0 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 73 0a  , this routines.
130b0 2a 2a 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c  ** records the l
130c0 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64  ast insert rowid
130d0 20 6f 66 20 62 6f 74 68 20 6f 72 64 69 6e 61 72   of both ordinar
130e0 79 20 74 61 62 6c 65 73 20 61 6e 64 20 5b 76 69  y tables and [vi
130f0 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a  rtual tables]..*
13100 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73  * ^If no success
13110 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a  ful [INSERT]s.**
13120 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
13130 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61  red on that data
13140 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
13150 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
13160 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e  d..**.** ^(If an
13170 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73   [INSERT] occurs
13180 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
13190 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76  r or within a [v
131a0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a  irtual table].**
131b0 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
131c0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
131d0 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69  return the [rowi
131e0 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74  d] of the insert
131f0 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e  ed.** row as lon
13200 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72  g as the trigger
13210 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
13220 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e  e method is runn
13230 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65  ing..** But once
13240 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
13250 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65  virtual table me
13260 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76  thod ends, the v
13270 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a  alue returned .*
13280 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  * by this routin
13290 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61  e reverts to wha
132a0 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20  t it was before 
132b0 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
132c0 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20  irtual.** table 
132d0 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a  method began.)^.
132e0 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52  **.** ^An [INSER
132f0 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  T] that fails du
13300 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
13310 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
13320 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
13330 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20  ul [INSERT] and 
13340 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
13350 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
13360 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
13370 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e  utine.  ^Thus IN
13380 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
13390 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
133a0 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
133b0 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
133c0 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
133d0 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
133e0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
133f0 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
13400 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
13410 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e  ertion fails.  ^
13420 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20  (When INSERT OR 
13430 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
13440 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
13450 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
13460 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
13470 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
13480 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
13490 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
134a0 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
134b0 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
134c0 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
134d0 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
134e0 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
134f0 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
13500 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
13510 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29  this interface.)
13520 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ^.**.** ^For the
13530 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
13540 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
13550 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
13560 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
13570 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
13580 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
13590 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
135a0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
135b0 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62  tion is accessib
135c0 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d  le to SQL statem
135d0 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20  ents via the.** 
135e0 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  [last_insert_row
135f0 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  id() SQL functio
13600 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
13610 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
13620 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49  erforms a new [I
13630 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61  NSERT] on the sa
13640 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  me.** database c
13650 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
13660 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  the [sqlite3_las
13670 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
13680 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ].** function is
13690 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
136a0 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
136b0 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
136c0 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76  ],.** then the v
136d0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
136e0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
136f0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69  nsert_rowid()] i
13700 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62  s.** unpredictab
13710 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
13720 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
13730 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
13740 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20  .** last insert 
13750 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69  [rowid]..*/.sqli
13760 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
13770 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
13780 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  wid(sqlite3*);..
13790 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
137a0 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72  Count The Number
137b0 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
137c0 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  d.**.** ^This fu
137d0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
137e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74  he number of dat
137f0 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20  abase rows that 
13800 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  were changed.** 
13810 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  or inserted or d
13820 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
13830 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
13840 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  leted SQL statem
13850 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64  ent.** on the [d
13860 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13870 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
13880 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
13890 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  eter..** ^(Only 
138a0 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65  changes that are
138b0 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66   directly specif
138c0 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45  ied by the [INSE
138d0 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a  RT], [UPDATE],.*
138e0 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  * or [DELETE] st
138f0 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e  atement are coun
13900 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20  ted.  Auxiliary 
13910 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
13920 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72  y.** triggers or
13930 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
13940 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63  tions] are not c
13950 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68  ounted.)^ Use th
13960 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f  e.** [sqlite3_to
13970 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  tal_changes()] f
13980 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20  unction to find 
13990 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
139a0 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69   of changes.** i
139b0 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73  ncluding changes
139c0 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67   caused by trigg
139d0 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20  ers and foreign 
139e0 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  key actions..**.
139f0 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61  ** ^Changes to a
13a00 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73   view that are s
13a10 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b  imulated by an [
13a20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
13a30 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63  er].** are not c
13a40 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65  ounted.  Only re
13a50 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73  al table changes
13a60 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   are counted..**
13a70 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61  .** ^(A "row cha
13a80 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65  nge" is a change
13a90 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77   to a single row
13aa0 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62   of a single tab
13ab0 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  le.** caused by 
13ac0 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54  an INSERT, DELET
13ad0 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61  E, or UPDATE sta
13ae0 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68  tement.  Rows th
13af0 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65  at.** are change
13b00 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74  d as side effect
13b10 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63  s of [REPLACE] c
13b20 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
13b30 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63  tion,.** rollbac
13b40 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  k, ABORT process
13b50 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45  ing, [DROP TABLE
13b60 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68  ], or by any oth
13b70 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73  er.** mechanisms
13b80 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
13b90 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
13ba0 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22  ges.)^.**.** A "
13bb0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22  trigger context"
13bc0 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65   is a scope of e
13bd0 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65  xecution that be
13be0 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73  gins and.** ends
13bf0 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74   with the script
13c00 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54 52   of a [CREATE TR
13c10 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d  IGGER | trigger]
13c20 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73  . .** Most SQL s
13c30 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a  tatements are.**
13c40 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69   evaluated outsi
13c50 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65  de of any trigge
13c60 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20  r.  This is the 
13c70 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74  "top level".** t
13c80 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20  rigger context. 
13c90 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69   If a trigger fi
13ca0 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  res from the top
13cb0 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77   level, a.** new
13cc0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
13cd0 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20   is entered for 
13ce0 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20  the duration of 
13cf0 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67  that one.** trig
13d00 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72  ger.  Subtrigger
13d10 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74  s create subcont
13d20 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64  exts for their d
13d30 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  uration..**.** ^
13d40 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  Calling [sqlite3
13d50 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c  _exec()] or [sql
13d60 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63  ite3_step()] rec
13d70 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a  ursively does.**
13d80 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65   not create a ne
13d90 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
13da0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  t..**.** ^This f
13db0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
13dc0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69  the number of di
13dd0 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
13de0 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20   in the.** most 
13df0 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
13e00 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
13e10 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
13e20 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72  n the same.** tr
13e30 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
13e40 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e  *.** ^Thus, when
13e50 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
13e60 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73   top level, this
13e70 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
13e80 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
13e90 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  of changes in th
13ea0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  e most recent IN
13eb0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
13ec0 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
13ed0 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74  also occurred at
13ee0 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20   the top level. 
13ef0 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f   ^(Within the bo
13f00 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c  dy of a trigger,
13f10 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
13f20 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66  changes() interf
13f30 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ace can be calle
13f40 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
13f50 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67  mber of.** chang
13f60 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
13f70 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
13f80 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
13f90 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73  , or DELETE.** s
13fa0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
13fb0 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20  the body of the 
13fc0 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a  same trigger..**
13fd0 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75   However, the nu
13fe0 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f  mber returned do
13ff0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
14000 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64  hanges.** caused
14010 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20   by subtriggers 
14020 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65  since those have
14030 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65   their own conte
14040 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  xt.)^.**.** See 
14050 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
14060 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
14070 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
14080 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
14090 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
140a0 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
140b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
140c0 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
140d0 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
140e0 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
140f0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
14100 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
14110 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
14120 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
14130 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
14140 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e  eturned.** is un
14150 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
14160 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
14170 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
14180 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
14190 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
141a0 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
141b0 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
141c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
141d0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
141e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20  e number of row 
141f0 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
14200 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b  y [INSERT],.** [
14210 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45  UPDATE] or [DELE
14220 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73  TE] statements s
14230 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61  ince the [databa
14240 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
14250 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28  as opened..** ^(
14260 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e  The count return
14270 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
14280 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  tal_changes() in
14290 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67  cludes all chang
142a0 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b  es.** from all [
142b0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
142c0 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78   trigger] contex
142d0 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d  ts and changes m
142e0 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69  ade by.** [forei
142f0 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e  gn key actions].
14300 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65   However,.** the
14310 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
14320 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20  include changes 
14330 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
14340 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  t [REPLACE] cons
14350 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72  traints,.** do r
14360 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52  ollbacks or ABOR
14370 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72  T processing, or
14380 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72   [DROP TABLE] pr
14390 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a  ocessing.  The.*
143a0 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74  * count does not
143b0 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66   include rows of
143c0 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65   views that fire
143d0 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
143e0 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f  trigger],.** tho
143f0 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45  ugh if the INSTE
14400 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61  AD OF trigger ma
14410 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69  kes changes of i
14420 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68  ts own, those ch
14430 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f  anges .** are co
14440 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65  unted.)^.** ^The
14450 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
14460 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
14470 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61  n counts the cha
14480 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a  nges as soon as.
14490 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
144a0 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d   that makes them
144b0 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77   is completed (w
144c0 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
144d0 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70  t handle.** is p
144e0 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
144f0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
14500 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
14510 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  )])..**.** See a
14520 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
14530 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
14540 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
14550 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
14560 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
14570 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
14580 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
14590 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
145a0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
145b0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
145c0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
145d0 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
145e0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
145f0 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
14600 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
14610 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
14620 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
14630 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
14640 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
14650 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
14660 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
14670 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
14680 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
14690 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a  unning Query.**.
146a0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
146b0 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
146c0 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
146d0 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
146e0 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
146f0 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
14700 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
14710 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
14720 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
14730 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
14740 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
14750 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
14760 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
14770 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
14780 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
14790 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
147a0 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
147b0 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
147c0 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
147d0 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
147e0 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
147f0 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
14800 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
14810 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
14820 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
14830 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
14840 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
14850 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
14860 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
14870 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14880 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
14890 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
148a0 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
148b0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
148c0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
148d0 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
148e0 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
148f0 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
14900 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
14910 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
14920 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
14930 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
14940 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
14950 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
14960 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
14970 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
14980 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
14990 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
149a0 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
149b0 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
149c0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
149d0 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
149e0 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
149f0 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
14a00 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
14a10 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
14a20 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
14a30 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
14a40 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
14a50 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
14a60 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
14a70 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
14a80 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
14a90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
14aa0 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
14ab0 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
14ac0 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
14ad0 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
14ae0 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
14af0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14b00 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
14b10 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
14b20 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
14b30 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
14b40 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
14b50 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
14b60 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
14b70 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
14b80 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
14b90 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
14ba0 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
14bb0 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
14bc0 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
14bd0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
14be0 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
14bf0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
14c00 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
14c10 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
14c20 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
14c30 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
14c40 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
14c50 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
14c60 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
14c70 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
14c80 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
14c90 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
14ca0 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
14cb0 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
14cc0 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
14cd0 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
14ce0 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
14cf0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
14d00 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
14d10 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
14d20 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
14d30 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  l returns..**.**
14d40 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
14d50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
14d60 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
14d70 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
14d80 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  * is running the
14d90 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
14da0 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
14db0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
14dc0 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
14dd0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
14de0 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
14df0 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
14e00 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
14e10 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
14e20 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
14e30 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d   during command-
14e40 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
14e50 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
14e60 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
14e70 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
14e80 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74  o form a complet
14e90 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
14ea0 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
14eb0 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
14ec0 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
14ed0 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
14ee0 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
14ef0 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20  arsing.  ^These 
14f00 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
14f10 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  1 if the input s
14f20 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
14f30 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
14f40 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
14f50 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69    ^A statement i
14f60 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
14f70 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
14f80 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
14f90 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
14fa0 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
14fb0 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
14fc0 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
14fd0 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
14fe0 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74  ^Semicolons that
14ff0 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
15000 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
15010 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
15020 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
15030 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
15040 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
15050 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
15060 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
15070 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
15080 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
15090 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
150a0 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
150b0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
150c0 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65  minator.  ^White
150d0 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d  space.** and com
150e0 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f  ments that follo
150f0 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69  w the final semi
15100 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65  colon are ignore
15110 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
15120 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
15130 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  0 if the stateme
15140 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65  nt is incomplete
15150 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f  .  ^If a.** memo
15160 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
15170 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ils, then SQLITE
15180 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e  _NOMEM is return
15190 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
151a0 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
151b0 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
151c0 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
151d0 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
151e0 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
151f0 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
15200 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65  *.** ^(If SQLite
15210 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
15220 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
15230 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
15240 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
15250 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
15260 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
15270 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
15280 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
15290 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
152a0 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
152b0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
152c0 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
152d0 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
152e0 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
152f0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
15300 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
15310 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
15320 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
15330 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
15340 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
15350 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e  L is complete.)^
15360 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
15370 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
15380 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65  plete()] must be
15390 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
153a0 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69  ed.** UTF-8 stri
153b0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ng..**.** The in
153c0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
153d0 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75  complete16()] mu
153e0 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
153f0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
15400 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
15410 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
15420 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
15430 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61  mplete(const cha
15440 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c  r *sql);.int sql
15450 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
15460 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
15470 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
15480 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
15490 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
154a0 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
154b0 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ors.**.** ^This 
154c0 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63  routine sets a c
154d0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
154e0 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69   that might be i
154f0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a  nvoked whenever.
15500 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  ** an attempt is
15510 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20   made to open a 
15520 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74  database table t
15530 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65  hat another thre
15540 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73  ad.** or process
15550 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a   has locked..**.
15560 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  ** ^If the busy 
15570 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
15580 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42  , then [SQLITE_B
15590 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
155a0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
155b0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
155c0 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
155d0 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
155e0 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62  lock.  ^If the b
155f0 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  usy callback.** 
15600 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
15610 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d  n the callback m
15620 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
15630 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
15640 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ts..**.** ^The f
15650 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
15660 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
15670 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
15680 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
15690 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
156a0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
156b0 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  to sqlite3_busy_
156c0 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65  handler().  ^The
156d0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
156e0 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20   to.** the busy 
156f0 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
15700 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
15710 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
15720 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
15730 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
15740 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69  d for this locki
15750 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
15760 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
15770 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
15780 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
15790 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
157a0 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
157b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
157c0 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
157d0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
157e0 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74  _BLOCKED] is ret
157f0 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  urned..** ^If th
15800 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
15810 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
15820 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70  n another attemp
15830 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20  t.** is made to 
15840 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
15850 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  e for reading an
15860 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
15870 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
15880 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
15890 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
158a0 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
158b0 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  t it will be inv
158c0 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  oked.** when the
158d0 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
158e0 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74  ntion. ^If SQLit
158f0 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61  e determines tha
15900 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  t invoking the b
15910 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63  usy.** handler c
15920 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
15930 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69   deadlock, it wi
15940 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20  ll go ahead and 
15950 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
15960 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  USY].** or [SQLI
15970 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
15980 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  ] instead of inv
15990 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68  oking the busy h
159a0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69  andler..** Consi
159b0 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77  der a scenario w
159c0 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73  here one process
159d0 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
159e0 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20  ad lock that.** 
159f0 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20  it is trying to 
15a00 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73  promote to a res
15a10 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a  erved lock and.*
15a20 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  * a second proce
15a30 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
15a40 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68  reserved lock th
15a50 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a  at it is trying.
15a60 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ** to promote to
15a70 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f   an exclusive lo
15a80 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ck.  The first p
15a90 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72  rocess cannot pr
15aa0 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65  oceed.** because
15ab0 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
15ac0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  y the second and
15ad0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
15ae0 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72  ess cannot.** pr
15af0 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74  oceed because it
15b00 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
15b10 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f  he first.  If bo
15b20 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20  th processes.** 
15b30 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20  invoke the busy 
15b40 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65  handlers, neithe
15b50 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20  r will make any 
15b60 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65  progress.  There
15b70 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  fore,.** SQLite 
15b80 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
15b90 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69  BUSY] for the fi
15ba0 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70  rst process, hop
15bb0 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a  ing that this.**
15bc0 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65   will induce the
15bd0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74   first process t
15be0 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65  o release its re
15bf0 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f  ad lock and allo
15c00 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  w.** the second 
15c10 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65  process to proce
15c20 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  ed..**.** ^The d
15c30 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
15c40 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
15c50 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
15c60 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20  _BUSY] error is 
15c70 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51  converted to [SQ
15c80 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
15c90 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ED].** when SQLi
15ca0 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64  te is in the mid
15cb0 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74  dle of a large t
15cc0 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65  ransaction where
15cd0 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e   all the.** chan
15ce0 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74  ges will not fit
15cf0 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d   into the in-mem
15d00 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69  ory cache.  SQLi
15d10 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61  te will.** alrea
15d20 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56  dy hold a RESERV
15d30 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64  ED lock on the d
15d40 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75  atabase file, bu
15d50 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f  t it needs.** to
15d60 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f   promote this lo
15d70 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20  ck to EXCLUSIVE 
15d80 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73  so that it can s
15d90 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61  pill cache.** pa
15da0 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ges into the dat
15db0 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f  abase file witho
15dc0 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75  ut harm to concu
15dd0 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73  rrent.** readers
15de0 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61  .  ^If it is una
15df0 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ble to promote t
15e00 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68  he lock, then th
15e10 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63  e in-memory.** c
15e20 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66  ache will be lef
15e30 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73  t in an inconsis
15e40 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73  tent state and s
15e50 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63  o the error.** c
15e60 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20  ode is promoted 
15e70 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76  from the relativ
15e80 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49  ely benign [SQLI
15e90 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74  TE_BUSY] to.** t
15ea0 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b  he more severe [
15eb0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
15ec0 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72  CKED].  ^This er
15ed0 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69  ror code promoti
15ee0 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20  on.** forces an 
15ef0 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61  automatic rollba
15f00 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65  ck of the change
15f10 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c  s.  See the.** <
15f20 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63  a href="/cvstrac
15f30 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69  /wiki?p=Corrupti
15f40 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
15f50 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70  rror">.** Corrup
15f60 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
15f70 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20  yError</a> wiki 
15f80 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75  page for a discu
15f90 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20  ssion of why.** 
15fa0 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e  this is importan
15fb0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  t..**.** ^(There
15fc0 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
15fd0 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
15fe0 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  er defined for e
15ff0 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
16000 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53   connection].  S
16010 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73  etting a new bus
16020 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73  y handler clears
16030 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73   any.** previous
16040 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29  ly set handler.)
16050 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61  ^  ^Note that ca
16060 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  lling [sqlite3_b
16070 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a  usy_timeout()].*
16080 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20  * will also set 
16090 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73  or clear the bus
160a0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  y handler..**.**
160b0 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   The busy callba
160c0 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61  ck should not ta
160d0 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77  ke any actions w
160e0 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a  hich modify the.
160f0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
16100 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
16110 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
16120 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20  dler.  Any such 
16130 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
16140 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
16150 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
16160 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
16170 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
16180 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
16190 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
161a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
161b0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
161c0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
161d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
161e0 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
161f0 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
16200 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b  d*,int), void*);
16210 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16220 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
16230 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  eout.**.** ^This
16240 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
16250 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
16260 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
16270 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
16280 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
16290 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
162a0 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
162b0 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
162c0 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
162d0 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
162e0 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
162f0 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
16300 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
16310 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
16320 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
16330 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
16340 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
16350 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
16360 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
16370 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
16380 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
16390 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
163a0 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
163b0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
163c0 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  KED]..**.** ^Cal
163d0 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
163e0 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
163f0 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
16400 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
16410 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
16420 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
16430 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
16440 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
16450 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
16460 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  r a particular.*
16470 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
16480 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20  ection] any any 
16490 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49  given moment.  I
164a0 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68  f another busy h
164b0 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65  andler.** was de
164c0 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73  fined  (using [s
164d0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
164e0 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f  ler()]) prior to
164f0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73   calling.** this
16500 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f   routine, that o
16510 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
16520 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a  r is cleared.)^.
16530 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
16540 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69  usy_timeout(sqli
16550 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  te3*, int ms);..
16560 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
16570 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74  Convenience Rout
16580 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67  ines For Running
16590 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54   Queries.**.** T
165a0 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20  his is a legacy 
165b0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69  interface that i
165c0 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20  s preserved for 
165d0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
165e0 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20  ibility..** Use 
165f0 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
16600 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65  e is not recomme
16610 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69  nded..**.** Defi
16620 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
16630 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
16640 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
16650 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
16660 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
16670 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
16680 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
16690 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
166a0 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
166b0 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
166c0 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
166d0 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
166e0 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
166f0 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
16700 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
16710 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
16720 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
16730 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
16740 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
16750 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
16760 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
16770 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
16780 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
16790 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
167a0 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
167b0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
167c0 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
167d0 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
167e0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
167f0 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
16800 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
16810 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
16820 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
16830 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
16840 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
16850 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
16860 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
16870 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
16880 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
16890 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
168a0 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
168b0 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
168c0 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
168d0 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
168e0 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
168f0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
16900 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
16910 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
16920 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
16930 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
16940 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
16950 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
16960 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
16970 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
16980 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
16990 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
169a0 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
169b0 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
169c0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
169d0 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
169e0 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
169f0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
16a00 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
16a10 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
16a20 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
16a30 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
16a40 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  le()]..**.** ^(A
16a50 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
16a60 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
16a70 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
16a80 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
16a90 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
16aa0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
16ab0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
16ac0 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
16ad0 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
16ae0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
16af0 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
16b00 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
16b10 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
16b20 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
16b30 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
16b40 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
16b50 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
16b60 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
16b70 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
16b80 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
16b90 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
16ba0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
16bb0 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
16bc0 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
16bd0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
16be0 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
16bf0 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
16c00 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
16c10 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
16c20 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
16c30 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
16c40 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
16c50 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
16c60 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
16c70 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
16c80 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
16c90 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
16ca0 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
16cb0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
16cc0 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
16cd0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
16ce0 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
16cf0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
16d00 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
16d10 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
16d20 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
16d30 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
16d40 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
16d50 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
16d60 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
16d70 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
16d80 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
16d90 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
16da0 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
16db0 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
16dc0 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
16dd0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
16de0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
16df0 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
16e00 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
16e10 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  er and returns a
16e20 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
16e30 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
16e40 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
16e50 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
16e60 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c  * After the appl
16e70 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  ication has fini
16e80 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65  shed with the re
16e90 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65  sult from sqlite
16ea0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a  3_get_table(),.*
16eb0 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74  * it must pass t
16ec0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
16ed0 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
16ee0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20  e3_free_table() 
16ef0 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72  in order to.** r
16f00 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
16f10 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
16f20 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ced.  Because of
16f30 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20   the way the.** 
16f40 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
16f50 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69  )] happens withi
16f60 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  n sqlite3_get_ta
16f70 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69  ble(), the calli
16f80 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  ng.** function m
16f90 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
16fa0 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  all [sqlite3_fre
16fb0 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
16fc0 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  Only.** [sqlite3
16fd0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
16fe0 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
16ff0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
17000 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
17010 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
17020 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
17030 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70  interface is imp
17040 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72  lemented as a wr
17050 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
17060 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
17070 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  .  The sqlite3_g
17080 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69  et_table() routi
17090 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ne does not have
170a0 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e   access.** to an
170b0 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20  y internal data 
170c0 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51  structures of SQ
170d0 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f  Lite.  It uses o
170e0 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a  nly the public.*
170f0 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69  * interface defi
17100 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20  ned here.  As a 
17110 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72  consequence, err
17120 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69  ors that occur i
17130 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72  n the.** wrapper
17140 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f   layer outside o
17150 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b  f the internal [
17160 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
17170 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  call are not.** 
17180 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62  reflected in sub
17190 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
171a0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
171b0 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  e()] or.** [sqli
171c0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
171d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
171e0 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
171f0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
17200 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
17210 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
17220 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
17230 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
17240 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
17250 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
17260 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
17270 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
17280 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
17290 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
172a0 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
172b0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
172c0 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
172d0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
172e0 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
172f0 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
17300 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
17310 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
17320 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
17330 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73  ere */.);.void s
17340 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
17350 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
17360 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
17370 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
17380 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
17390 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
173a0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
173b0 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74  work-alikes of t
173c0 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
173d0 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
173e0 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
173f0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
17400 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
17410 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
17420 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  nd sqlite3_vmpri
17430 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77  ntf() routines w
17440 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65  rite their.** re
17450 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72  sults into memor
17460 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
17470 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
17480 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
17490 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
174a0 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
174b0 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
174c0 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
174d0 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42  te3_free()].  ^B
174e0 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
174f0 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
17500 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
17510 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75  3_malloc()] is u
17520 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
17530 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
17540 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
17550 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
17560 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
17570 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
17580 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
17590 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
175a0 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
175b0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
175c0 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
175d0 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
175e0 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
175f0 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
17600 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
17610 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
17620 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
17630 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74  t parameter. Not
17640 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72  e that the order
17650 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
17660 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20   two parameters 
17670 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d  is reversed from
17680 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20   snprintf().)^  
17690 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69  This is an.** hi
176a0 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e  storical acciden
176b0 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65  t that cannot be
176c0 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62   fixed without b
176d0 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77  reaking.** backw
176e0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
176f0 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f  ty.  ^(Note also
17700 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
17710 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
17720 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
17730 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
17740 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
17750 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
17760 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
17770 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
17780 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74  fer.)^  We admit
17790 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d   that.** the num
177a0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
177b0 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20  s written would 
177c0 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c  be a more useful
177d0 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
177e0 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63   but we cannot c
177f0 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d  hange the implem
17800 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
17810 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
17820 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72  * now without br
17830 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69  eaking compatibi
17840 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  lity..**.** ^As 
17850 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
17860 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
17870 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
17880 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
17890 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
178a0 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
178b0 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
178c0 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
178d0 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
178e0 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f  er "n" is the to
178f0 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20  tal size of the 
17900 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e  buffer, includin
17910 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74  g space for.** t
17920 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
17930 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67  or.  So the long
17940 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20  est string that 
17950 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  can be completel
17960 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c  y.** written wil
17970 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74  l be n-1 charact
17980 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ers..**.** ^The 
17990 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
179a0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61  f() routine is a
179b0 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e   varargs version
179c0 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
179d0 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  intf()..**.** Th
179e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c  ese routines all
179f0 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20   implement some 
17a00 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61  additional forma
17a10 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73  tting.** options
17a20 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c   that are useful
17a30 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e   for constructin
17a40 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  g SQL statements
17a50 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20  ..** All of the 
17a60 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66  usual printf() f
17a70 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
17a80 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64  s apply.  In add
17a90 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20  ition, there.** 
17aa0 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51  is are "%q", "%Q
17ab0 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69  ", and "%z" opti
17ac0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ons..**.** ^(The
17ad0 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
17ae0 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
17af0 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
17b00 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65  a null-terminate
17b10 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d  d.** string from
17b20 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69   the argument li
17b30 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f  st.  But %q also
17b40 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27   doubles every '
17b50 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  \'' character..*
17b60 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64  * %q is designed
17b70 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
17b80 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
17b90 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67  .)^  By doubling
17ba0 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68   each '\''.** ch
17bb0 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70  aracter it escap
17bc0 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65  es that characte
17bd0 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20  r and allows it 
17be0 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  to be inserted i
17bf0 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  nto.** the strin
17c00 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  g..**.** For exa
17c10 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65  mple, assume the
17c20 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65   string variable
17c30 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20   zText contains 
17c40 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  text as follows:
17c50 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
17c60 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
17c70 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73  r *zText = "It's
17c80 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a   a happy day!";.
17c90 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
17ca0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65  quote>.**.** One
17cb0 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65   can use this te
17cc0 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  xt in an SQL sta
17cd0 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77  tement as follow
17ce0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
17cf0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
17d00 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
17d10 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
17d20 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
17d30 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54  ALUES('%q')", zT
17d40 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
17d50 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
17d60 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
17d70 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
17d80 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
17d90 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
17da0 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66  Because the %q f
17db0 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20  ormat string is 
17dc0 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63  used, the '\'' c
17dd0 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78  haracter in zTex
17de0 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20  t.** is escaped 
17df0 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65  and the SQL gene
17e00 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c  rated is as foll
17e10 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
17e20 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
17e30 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
17e40 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27  le1 VALUES('It''
17e50 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
17e60 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
17e70 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
17e80 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20  is is correct.  
17e90 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69  Had we used %s i
17ea0 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68  nstead of %q, th
17eb0 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a  e generated SQL.
17ec0 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f  ** would have lo
17ed0 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a  oked like this:.
17ee0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
17ef0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
17f00 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
17f10 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61  ALUES('It's a ha
17f20 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c  ppy day!');.** <
17f30 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
17f40 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65  e>.**.** This se
17f50 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20  cond example is 
17f60 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72  an SQL syntax er
17f70 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72  ror.  As a gener
17f80 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75  al rule you shou
17f90 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  ld.** always use
17fa0 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %q instead of %
17fb0 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  s when inserting
17fc0 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72   text into a str
17fd0 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a  ing literal..**.
17fe0 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69  ** ^(The %Q opti
17ff0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71  on works like %q
18000 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20   except it also 
18010 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74  adds single quot
18020 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65  es around.** the
18030 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
18040 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41  total string.  A
18050 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20  dditionally, if 
18060 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
18070 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
18080 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
18090 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
180a0 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
180b0 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
180c0 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  .** single quote
180d0 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65  s).)^  So, for e
180e0 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c  xample, one coul
180f0 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  d say:.**.** <bl
18100 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
18110 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
18120 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
18130 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
18140 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20  le VALUES(%Q)", 
18150 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
18160 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
18170 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
18180 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
18190 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
181a0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
181b0 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65  * The code above
181c0 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63   will render a c
181d0 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65  orrect SQL state
181e0 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c  ment in the zSQL
181f0 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65  .** variable eve
18200 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76  n if the zText v
18210 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
18220 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
18230 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d   ^(The "%z" form
18240 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f  atting option wo
18250 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75  rks like "%s" bu
18260 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  t with the.** ad
18270 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
18280 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
18290 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
182a0 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
182b0 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
182c0 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
182d0 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
182e0 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63  t string.)^.*/.c
182f0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72  har *sqlite3_mpr
18300 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
18310 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c  ,...);.char *sql
18320 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f  ite3_vmprintf(co
18330 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
18340 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  st);.char *sqlit
18350 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  e3_snprintf(int,
18360 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
18370 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73  *, ...);.char *s
18380 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
18390 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
183a0 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
183b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
183c0 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
183d0 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a  tion Subsystem.*
183e0 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
183f0 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20  core uses these 
18400 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66  three routines f
18410 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77  or all of its ow
18420 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65  n.** internal me
18430 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
18440 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e  needs. "Core" in
18450 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
18460 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e  ntence.** does n
18470 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61  ot include opera
18480 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
18490 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65  ific VFS impleme
184a0 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a  ntation.  The.**
184b0 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65   Windows VFS use
184c0 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28  s native malloc(
184d0 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72  ) and free() for
184e0 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73   some operations
184f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
18500 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f  ite3_malloc() ro
18510 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
18520 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f  pointer to a blo
18530 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  ck.** of memory 
18540 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
18550 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72   in length, wher
18560 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d  e N is the param
18570 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  eter..** ^If sql
18580 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
18590 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69   unable to obtai
185a0 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65  n sufficient fre
185b0 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20  e.** memory, it 
185c0 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
185d0 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65  ointer.  ^If the
185e0 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a   parameter N to.
185f0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
18600 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e  c() is zero or n
18610 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c  egative then sql
18620 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65  ite3_malloc() re
18630 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  turns.** a NULL 
18640 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
18650 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
18660 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f  free() with a po
18670 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79  inter previously
18680 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
18690 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
186a0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
186b0 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74  loc() releases t
186c0 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a  hat memory so.**
186d0 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62   that it might b
186e0 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20  e reused.  ^The 
186f0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72  sqlite3_free() r
18700 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e  outine is.** a n
18710 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65  o-op if is calle
18720 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
18730 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20  inter.  Passing 
18740 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
18750 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  * to sqlite3_fre
18760 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e  e() is harmless.
18770 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72    After being fr
18780 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73  eed, memory.** s
18790 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65  hould neither be
187a0 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65   read nor writte
187b0 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67  n.  Even reading
187c0 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65   previously free
187d0 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68  d.** memory migh
187e0 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65  t result in a se
187f0 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
18800 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
18810 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72   error..** Memor
18820 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20  y corruption, a 
18830 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
18840 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76  lt, or other sev
18850 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67  ere error.** mig
18860 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c  ht result if sql
18870 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63  ite3_free() is c
18880 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e  alled with a non
18890 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68  -NULL pointer th
188a0 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62  at.** was not ob
188b0 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
188c0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
188d0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
188e0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  )..**.** ^(The s
188f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
18900 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
18910 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
18920 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
18930 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
18940 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
18950 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  s, where N is th
18960 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
18970 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f  meter.  The memo
18980 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
18990 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74   be resized is t
189a0 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
189b0 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68  meter.)^ ^ If th
189c0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
189d0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
189e0 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e  lloc().** is a N
189f0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
18a00 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73   its behavior is
18a10 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61   identical to ca
18a20 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
18a30 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65  _malloc(N) where
18a40 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
18a50 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
18a60 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
18a70 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f  .** ^If the seco
18a80 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
18a90 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
18aa0 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20  ) is zero or.** 
18ab0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68  negative then th
18ac0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78  e behavior is ex
18ad0 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61  actly the same a
18ae0 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  s calling.** sql
18af0 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65  ite3_free(P) whe
18b00 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73  re P is the firs
18b10 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
18b20 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
18b30 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65  ..** ^sqlite3_re
18b40 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
18b50 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  a pointer to a m
18b60 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
18b70 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
18b80 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  N bytes in size 
18b90 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69  or NULL if suffi
18ba0 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20  cient memory is 
18bb0 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  unavailable..** 
18bc0 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a  ^If M is the siz
18bd0 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  e of the prior a
18be0 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
18bf0 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a  min(N,M) bytes.*
18c00 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  * of the prior a
18c10 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f  llocation are co
18c20 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65  pied into the be
18c30 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65  ginning of buffe
18c40 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  r returned.** by
18c50 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
18c60 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  () and the prior
18c70 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
18c80 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  reed..** ^If sql
18c90 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
18ca0 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65  eturns NULL, the
18cb0 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  n the prior allo
18cc0 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74  cation.** is not
18cd0 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   freed..**.** ^T
18ce0 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e  he memory return
18cf0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ed by sqlite3_ma
18d00 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74  lloc() and sqlit
18d10 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
18d20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
18d30 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
18d40 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
18d50 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62  , or to a.** 4 b
18d60 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20  yte boundary if 
18d70 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59  the [SQLITE_4_BY
18d80 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f  TE_ALIGNED_MALLO
18d90 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  C] compile-time.
18da0 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  ** option is use
18db0 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69  d..**.** In SQLi
18dc0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
18dd0 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77   and 3.5.1, it w
18de0 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64  as possible to d
18df0 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c  efine.** the SQL
18e00 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f  ITE_OMIT_MEMORY_
18e10 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68  ALLOCATION which
18e20 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65   would cause the
18e30 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70   built-in.** imp
18e40 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
18e50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  hese routines to
18e60 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68   be omitted.  Th
18e70 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  at capability.**
18e80 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72   is no longer pr
18e90 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75  ovided.  Only bu
18ea0 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
18eb0 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20  locators can be 
18ec0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  used..**.** The 
18ed0 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72  Windows OS inter
18ee0 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73  face layer calls
18ef0 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d  .** the system m
18f00 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
18f10 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e  () directly when
18f20 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66   converting.** f
18f30 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e  ilenames between
18f40 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   the UTF-8 encod
18f50 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69  ing used by SQLi
18f60 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76  te.** and whatev
18f70 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f  er filename enco
18f80 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20  ding is used by 
18f90 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57  the particular W
18fa0 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c  indows.** instal
18fb0 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20  lation.  Memory 
18fc0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
18fd0 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c 20  s are detected, 
18fe0 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20  but.** they are 
18ff0 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73  reported back as
19000 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   [SQLITE_CANTOPE
19010 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  N] or.** [SQLITE
19020 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74  _IOERR] rather t
19030 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  han [SQLITE_NOME
19040 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f  M]..**.** The po
19050 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20  inter arguments 
19060 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
19070 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
19080 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d  _realloc()].** m
19090 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55  ust be either NU
190a0 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74  LL or else point
190b0 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ers obtained fro
190c0 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76  m a prior.** inv
190d0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
190e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
190f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
19100 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a  c()] that have.*
19110 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72  * not yet been r
19120 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eleased..**.** T
19130 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
19140 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20  ust not read or 
19150 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f  write any part o
19160 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20  f.** a block of 
19170 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20  memory after it 
19180 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65  has been release
19190 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
191a0 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b  te3_free()] or [
191b0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
191c0 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  )]..*/.void *sql
191d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29  ite3_malloc(int)
191e0 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
191f0 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69  realloc(void*, i
19200 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
19210 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a  3_free(void*);..
19220 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19230 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
19240 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a   Statistics.**.*
19250 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
19260 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
19270 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
19280 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
19290 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
192a0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
192b0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
192c0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
192d0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
192e0 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
192f0 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
19300 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
19310 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
19320 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
19330 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
19340 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
19350 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
19360 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  tes.** of memory
19370 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
19380 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
19390 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
193a0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
193b0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
193c0 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
193d0 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
193e0 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73  m.** value of [s
193f0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
19400 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
19410 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
19420 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  ** was last rese
19430 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  t.  ^The values 
19440 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
19450 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
19460 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
19470 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
19480 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20  ater()] include 
19490 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20  any overhead.** 
194a0 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
194b0 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
194c0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
194d0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
194e0 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
194f0 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
19500 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
19510 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72  tem library.** r
19520 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
19530 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
19540 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
19550 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68  ^The memory high
19560 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
19570 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
19580 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
19590 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
195a0 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
195b0 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
195c0 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
195d0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
195e0 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
195f0 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74    ^The value ret
19600 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
19610 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
19620 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
19630 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
19640 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65  .** prior to the
19650 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74   reset..*/.sqlit
19660 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
19670 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
19680 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  d);.sqlite3_int6
19690 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
196a0 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
196b0 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
196c0 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
196d0 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
196e0 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a   Generator.**.**
196f0 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
19700 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
19710 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
19720 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
19730 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
19740 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
19750 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
19760 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
19770 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
19780 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
19790 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
197a0 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
197b0 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
197c0 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
197d0 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
197e0 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
197f0 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
19800 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
19810 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
19820 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
19830 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
19840 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
19850 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
19860 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  ..**.** ^A call 
19870 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
19880 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
19890 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
198a0 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a  o buffer P..**.*
198b0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d  * ^The first tim
198c0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
198d0 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65  s invoked (eithe
198e0 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20  r internally or 
198f0 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  by.** the applic
19900 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20  ation) the PRNG 
19910 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20  is seeded using 
19920 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
19930 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ned.** from the 
19940 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68  xRandomness meth
19950 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
19960 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
19970 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61  object..** ^On a
19980 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ll subsequent in
19990 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70  vocations, the p
199a0 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73  seudo-randomness
199b0 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a   is generated.**
199c0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20   internally and 
199d0 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65  without recourse
199e0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
199f0 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73  _vfs] xRandomnes
19a00 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a  s.** method..*/.
19a10 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e  void sqlite3_ran
19a20 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76  domness(int N, v
19a30 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid *P);../*.** 
19a40 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
19a50 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61  e-Time Authoriza
19a60 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
19a70 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
19a80 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20  ne registers an 
19a90 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
19aa0 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
19ab0 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
19ac0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
19ad0 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20  supplied in the 
19ae0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
19af0 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  ** ^The authoriz
19b00 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
19b10 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
19b20 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69  atements are bei
19b30 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62  ng compiled.** b
19b40 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
19b50 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
19b60 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70  iants [sqlite3_p
19b70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a  repare_v2()],.**
19b80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
19b90 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  e16()] and [sqli
19ba0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
19bb0 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75  ()].  ^At variou
19bc0 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69  s.** points duri
19bd0 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69  ng the compilati
19be0 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c  on process, as l
19bf0 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72  ogic is being cr
19c00 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66  eated.** to perf
19c10 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69  orm various acti
19c20 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69  ons, the authori
19c30 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
19c40 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65  invoked to.** se
19c50 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f  e if those actio
19c60 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20  ns are allowed. 
19c70 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
19c80 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
19c90 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
19ca0 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
19cb0 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
19cc0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
19cd0 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
19ce0 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
19cf0 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
19d00 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
19d10 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
19d20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
19d30 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
19d40 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
19d50 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
19d60 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
19d70 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
19d80 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
19d90 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
19da0 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
19db0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
19dc0 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
19dd0 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
19de0 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
19df0 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
19e00 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
19e10 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
19e20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
19e30 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
19e40 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
19e50 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
19e60 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
19e70 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
19e80 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
19e90 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
19ea0 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
19eb0 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68  sted is ok.  ^Wh
19ec0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
19ed0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
19ee0 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
19ef0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
19f00 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
19f10 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
19f20 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
19f30 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
19f40 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
19f50 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
19f60 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
19f70 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a  ss is denied. .*
19f80 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
19f90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
19fa0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
19fb0 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
19fc0 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
19fd0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
19fe0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
19ff0 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
1a000 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ce. ^The second 
1a010 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
1a020 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
1a030 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49  an integer [SQLI
1a040 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
1a050 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
1a060 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72  ifies.** the par
1a070 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74  ticular action t
1a080 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
1a090 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f   ^The third thro
1a0a0 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
1a0b0 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
1a0c0 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f  allback are zero
1a0d0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
1a0e0 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
1a0f0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64   additional.** d
1a100 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
1a110 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
1a120 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
1a130 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
1a140 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52  ode is [SQLITE_R
1a150 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20  EAD].** and the 
1a160 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1a170 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1a180 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72   then the.** [pr
1a190 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1a1a0 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  ] statement is c
1a1b0 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75  onstructed to su
1a1c0 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55  bstitute.** a NU
1a1d0 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
1a1e0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
1a1f0 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
1a200 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65   have.** been re
1a210 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b  ad if [SQLITE_OK
1a220 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72  ] had been retur
1a230 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ned.  The [SQLIT
1a240 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74  E_IGNORE].** ret
1a250 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  urn can be used 
1a260 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75  to deny an untru
1a270 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73  sted user access
1a280 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a   to individual.*
1a290 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74  * columns of a t
1a2a0 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  able..** ^If the
1a2b0 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
1a2c0 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20  [SQLITE_DELETE] 
1a2d0 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
1a2e0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
1a2f0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
1a300 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70   the [DELETE] op
1a310 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73  eration proceeds
1a320 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75   but the.** [tru
1a330 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69  ncate optimizati
1a340 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20  on] is disabled 
1a350 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65  and all rows are
1a360 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64   deleted individ
1a370 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  ually..**.** An 
1a380 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73  authorizer is us
1a390 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
1a3a0 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
1a3b0 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61  ring].** SQL sta
1a3c0 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20  tements from an 
1a3d0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
1a3e0 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74  , to ensure that
1a3f0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1a400 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72  nts.** do not tr
1a410 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61  y to access data
1a420 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c   they are not al
1a430 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72  lowed to see, or
1a440 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
1a450 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63  t.** try to exec
1a460 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74  ute malicious st
1a470 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61  atements that da
1a480 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73  mage the databas
1a490 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
1a4a0 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
1a4b0 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75  on may allow a u
1a4c0 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62  ser to enter arb
1a4d0 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75  itrary.** SQL qu
1a4e0 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61  eries for evalua
1a4f0 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61  tion by a databa
1a500 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70  se.  But the app
1a510 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a  lication does.**
1a520 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73   not want the us
1a530 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f  er to be able to
1a540 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20   make arbitrary 
1a550 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a  changes to the.*
1a560 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20  * database.  An 
1a570 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64  authorizer could
1a580 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20   then be put in 
1a590 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a  place while the.
1a5a0 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ** user-entered 
1a5b0 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71  SQL is being [sq
1a5c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
1a5d0 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a  prepared] that.*
1a5e0 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72  * disallows ever
1a5f0 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53  ything except [S
1a600 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
1a610 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  s..**.** Applica
1a620 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20  tions that need 
1a630 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66  to process SQL f
1a640 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f  rom untrusted so
1a650 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61  urces.** might a
1a660 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77  lso consider low
1a670 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c  ering resource l
1a680 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c  imits using [sql
1a690 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
1a6a0 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61   and limiting da
1a6b0 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e  tabase size usin
1a6c0 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f  g the [max_page_
1a6d0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a  count] [PRAGMA].
1a6e0 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74  ** in addition t
1a6f0 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f  o using an autho
1a700 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  rizer..**.** ^(O
1a710 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74  nly a single aut
1a720 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69  horizer can be i
1a730 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74  n place on a dat
1a740 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a750 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20  .** at a time.  
1a760 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  Each call to sql
1a770 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1a780 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68  zer overrides th
1a790 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61  e.** previous ca
1a7a0 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20  ll.)^  ^Disable 
1a7b0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62  the authorizer b
1a7c0 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e  y installing a N
1a7d0 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ULL callback..**
1a7e0 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
1a7f0 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
1a800 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  efault..**.** Th
1a810 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1a820 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
1a830 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
1a840 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
1a850 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1a860 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1a870 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ked the authoriz
1a880 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  er callback..** 
1a890 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
1a8a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1a8b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
1a8c0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
1a8d0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
1a8e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
1a8f0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
1a900 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
1a910 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
1a920 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69  *.** ^When [sqli
1a930 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1a940 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65  ] is used to pre
1a950 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
1a960 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  , the.** stateme
1a970 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70  nt might be re-p
1a980 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b  repared during [
1a990 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1a9a0 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68  due to a .** sch
1a9b0 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e  ema change.  Hen
1a9c0 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ce, the applicat
1a9d0 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72  ion should ensur
1a9e0 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f  e that the.** co
1a9f0 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72  rrect authorizer
1aa00 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e   callback remain
1aa10 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e  s in place durin
1aa20 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  g the [sqlite3_s
1aa30 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  tep()]..**.** ^N
1aa40 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
1aa50 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1aa60 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
1aa70 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69   during.** [sqli
1aa80 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
1aa90 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
1aaa0 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
1aab0 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
1aac0 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
1aad0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
1aae0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
1aaf0 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73  )], unless.** as
1ab00 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70   stated in the p
1ab10 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70  revious paragrap
1ab20 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  h, sqlite3_step(
1ab30 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c  ) invokes.** sql
1ab40 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1ab50 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61  ) to reprepare a
1ab60 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
1ab70 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
1ab80 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1ab90 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1aba0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69  .  sqlite3*,.  i
1abb0 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64  nt (*xAuth)(void
1abc0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
1abd0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
1abe0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1abf0 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  char*),.  void *
1ac00 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a  pUserData.);../*
1ac10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
1ac20 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20  thorizer Return 
1ac30 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
1ac40 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1ac50 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1ac60 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
1ac70 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
1ac80 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
1ac90 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
1aca0 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
1acb0 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
1acc0 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
1acd0 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
1ace0 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
1acf0 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
1ad00 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
1ad10 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1ad20 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
1ad30 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
1ad40 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1ad50 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
1ad60 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49  * Note that SQLI
1ad70 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73  TE_IGNORE is als
1ad80 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c  o used as a [SQL
1ad90 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72  ITE_ROLLBACK | r
1ada0 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66  eturn code].** f
1adb0 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
1adc0 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
1add0 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  t()] interface..
1ade0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1adf0 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
1ae00 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
1ae10 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
1ae20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
1ae30 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
1ae40 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
1ae50 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
1ae60 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
1ae70 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
1ae80 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1ae90 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
1aea0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1aeb0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1aec0 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
1aed0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
1aee0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
1aef0 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
1af00 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63  d to authorize c
1af10 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
1af20 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
1af30 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1af40 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
1af50 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
1af60 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
1af70 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
1af80 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
1af90 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
1afa0 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
1afb0 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
1afc0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
1afd0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1afe0 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
1aff0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
1b000 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
1b010 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
1b020 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
1b030 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72   to be.** author
1b040 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
1b050 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
1b060 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
1b070 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
1b080 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
1b090 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
1b0a0 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
1b0b0 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
1b0c0 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
1b0d0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
1b0e0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28  d parameter.  ^(
1b0f0 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
1b100 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
1b110 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1b120 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1b130 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
1b140 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
1b150 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
1b160 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68  ble.)^  ^The 6th
1b170 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1b180 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1b190 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
1b1a0 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
1b1b0 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
1b1c0 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
1b1d0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
1b1e0 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
1b1f0 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
1b200 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
1b210 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
1b220 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
1b230 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
1b240 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1b250 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1b260 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
1b270 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
1b280 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
1b290 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1b2a0 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
1b2b0 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
1b2c0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1b2d0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1b2e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1b2f0 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
1b300 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
1b310 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1b320 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1b330 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1b340 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
1b350 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
1b360 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1b370 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1b380 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1b390 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
1b3a0 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
1b3b0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1b3c0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1b3d0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1b3e0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
1b3f0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1b400 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1b410 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b420 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1b430 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
1b440 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1b450 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1b460 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b470 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
1b480 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
1b490 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1b4a0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1b4b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b4c0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
1b4d0 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
1b4e0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1b4f0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1b500 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b510 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
1b520 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
1b530 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1b540 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b550 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b560 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
1b570 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
1b580 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1b590 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b5a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b5b0 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
1b5c0 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
1b5d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1b5e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1b5f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b600 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
1b610 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
1b620 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1b630 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1b640 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b650 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
1b660 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
1b670 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1b680 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1b690 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b6a0 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
1b6b0 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
1b6c0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1b6d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1b6e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1b6f0 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
1b700 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
1b710 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1b720 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1b730 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1b740 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
1b750 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
1b760 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1b770 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1b780 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1b790 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
1b7a0 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
1b7b0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1b7c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1b7d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
1b7e0 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
1b7f0 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
1b800 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1b810 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1b820 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
1b830 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
1b840 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
1b850 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
1b860 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
1b870 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
1b880 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1b890 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
1b8a0 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
1b8b0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1b8c0 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
1b8d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
1b8e0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
1b8f0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1b900 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b910 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
1b920 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
1b930 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
1b940 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1b950 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b960 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
1b970 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
1b980 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1b990 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
1b9a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b9b0 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
1b9c0 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
1b9d0 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
1b9e0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1b9f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ba00 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
1ba10 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
1ba20 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
1ba30 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1ba40 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ba50 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
1ba60 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
1ba70 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
1ba80 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1ba90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1baa0 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
1bab0 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
1bac0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1bad0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1bae0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1baf0 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
1bb00 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
1bb10 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1bb20 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1bb30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1bb40 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
1bb50 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
1bb60 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
1bb70 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
1bb80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1bb90 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
1bba0 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
1bbb0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
1bbc0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
1bbd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
1bbe0 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
1bbf0 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c      31   /* NULL
1bc00 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63              Func
1bc10 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23  tion Name   */.#
1bc20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41  define SQLITE_SA
1bc30 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20  VEPOINT         
1bc40 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61     32   /* Opera
1bc50 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70  tion       Savep
1bc60 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64  oint Name  */.#d
1bc70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
1bc80 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
1bc90 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
1bca0 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  ger used */../*.
1bcb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61  ** CAPI3REF: Tra
1bcc0 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69  cing And Profili
1bcd0 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
1bce0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1bcf0 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  s register callb
1bd00 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
1bd10 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66  at can be used f
1bd20 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e  or.** tracing an
1bd30 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20  d profiling the 
1bd40 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c  execution of SQL
1bd50 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
1bd60 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
1bd70 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1bd80 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1bd90 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b  trace() is invok
1bda0 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73  ed at.** various
1bdb0 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53   times when an S
1bdc0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  QL statement is 
1bdd0 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71  being run by [sq
1bde0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1bdf0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
1be00 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20  race() callback 
1be10 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
1be20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
1be30 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20  g of the.** SQL 
1be40 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
1be50 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
1be60 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
1be70 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64  cuting..** ^(Add
1be80 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f  itional sqlite3_
1be90 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
1bea0 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
1beb0 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72   as each trigger
1bec0 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73  ed subprogram is
1bed0 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63   entered.  The c
1bee0 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69  allbacks for tri
1bef0 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e  ggers.** contain
1bf00 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d   a UTF-8 SQL com
1bf10 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69  ment that identi
1bf20 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72  fies the trigger
1bf30 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  .)^.**.** ^The c
1bf40 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1bf50 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
1bf60 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
1bf70 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
1bf80 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
1bf90 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
1bfa0 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
1bfb0 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a  lback contains.*
1bfc0 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
1bfd0 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e  tatement text an
1bfe0 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  d an estimate of
1bff0 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65   wall-clock time
1c000 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20  .** of how long 
1c010 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74  that statement t
1c020 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68  ook to run.  ^Th
1c030 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
1c040 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e  ck.** time is in
1c050 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65   units of nanose
1c060 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74  conds, however t
1c070 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
1c080 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  mentation.** is 
1c090 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20  only capable of 
1c0a0 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f  millisecond reso
1c0b0 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69  lution so the si
1c0c0 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63  x least signific
1c0d0 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e  ant.** digits in
1c0e0 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65   the time are me
1c0f0 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75  aningless.  Futu
1c100 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1c110 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70  QLite.** might p
1c120 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72  rovide greater r
1c130 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65  esolution on the
1c140 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61   profiler callba
1c150 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  ck.  The.** sqli
1c160 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75  te3_profile() fu
1c170 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64  nction is consid
1c180 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61  ered experimenta
1c190 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a  l and is.** subj
1c1a0 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
1c1b0 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
1c1c0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76   of SQLite..*/.v
1c1d0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61  oid *sqlite3_tra
1c1e0 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ce(sqlite3*, voi
1c1f0 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a  d(*xTrace)(void*
1c200 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76  ,const char*), v
1c210 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58  oid*);.SQLITE_EX
1c220 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20  PERIMENTAL void 
1c230 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  *sqlite3_profile
1c240 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f  (sqlite3*,.   vo
1c250 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f  id(*xProfile)(vo
1c260 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  id*,const char*,
1c270 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c  sqlite3_uint64),
1c280 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
1c290 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20  CAPI3REF: Query 
1c2a0 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63  Progress Callbac
1c2b0 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ks.**.** ^The sq
1c2c0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
1c2d0 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20  andler(D,N,X,P) 
1c2e0 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
1c2f0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
1c300 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62   function X to b
1c310 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  e invoked period
1c320 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
1c330 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ng running calls
1c340 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
1c350 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
1c360 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73  3_step()] and [s
1c370 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1c380 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62  ()] for.** datab
1c390 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
1c3a0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73  .  An example us
1c3b0 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e  e for this.** in
1c3c0 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
1c3d0 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
1c3e0 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
1c3f0 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  query..**.** ^Th
1c400 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  e parameter P is
1c410 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
1c420 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
1c430 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a  meter to the .**
1c440 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1c450 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61  on X.  ^The para
1c460 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 6e  meter N is the n
1c470 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69  umber of .** [vi
1c480 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e  rtual machine in
1c490 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74  structions] that
1c4a0 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62   are evaluated b
1c4b0 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76  etween successiv
1c4c0 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
1c4d0 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   of the callback
1c4e0 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20   X..**.** ^Only 
1c4f0 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73  a single progres
1c500 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65  s handler may be
1c510 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20   defined at one 
1c520 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74  time per.** [dat
1c530 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c540 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77  ]; setting a new
1c550 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1c560 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a  r cancels the.**
1c570 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74   old one.  ^Sett
1c580 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20  ing parameter X 
1c590 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73  to NULL disables
1c5a0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
1c5b0 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70  ndler..** ^The p
1c5c0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1c5d0 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64  is also disabled
1c5e0 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f   by setting N to
1c5f0 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a   a value less.**
1c600 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e   than 1..**.** ^
1c610 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
1c620 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1c630 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
1c640 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  peration is.** i
1c650 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
1c660 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
1c670 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1c680 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
1c690 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
1c6a0 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
1c6b0 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   box..**.** The 
1c6c0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1c6d0 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
1c6e0 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
1c6f0 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
1c700 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1c710 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
1c720 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67  invoked the prog
1c730 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
1c740 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
1c750 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1c760 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
1c770 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
1c780 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
1c790 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1c7a0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
1c7b0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
1c7c0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
1c7d0 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  **.*/.void sqlit
1c7e0 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1c7f0 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
1c800 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
1c810 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
1c820 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
1c830 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
1c840 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a  e Connection.**.
1c850 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
1c860 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
1c870 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
1c880 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20  as specified by 
1c890 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  the .** filename
1c8a0 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20   argument. ^The 
1c8b0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1c8c0 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
1c8d0 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a   as UTF-8 for.**
1c8e0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1c8f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
1c900 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46  _v2() and as UTF
1c910 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
1c920 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20  e byte.** order 
1c930 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
1c940 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62  16(). ^(A [datab
1c950 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1c960 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c  handle is usuall
1c970 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e  y.** returned in
1c980 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20   *ppDb, even if 
1c990 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
1c9a0 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70    The only excep
1c9b0 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20  tion is that.** 
1c9c0 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  if SQLite is una
1c9d0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
1c9e0 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
1c9f0 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
1ca00 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77  ect,.** a NULL w
1ca10 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69  ill be written i
1ca20 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61  nto *ppDb instea
1ca30 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74  d of a pointer t
1ca40 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a  o the [sqlite3].
1ca50 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49  ** object.)^ ^(I
1ca60 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
1ca70 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
1ca80 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
1ca90 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20  sfully, then.** 
1caa0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
1cab0 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
1cac0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
1cad0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
1cae0 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  )^ ^The.** [sqli
1caf0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72  te3_errmsg()] or
1cb00 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1cb10 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63  16()] routines c
1cb20 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
1cb30 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69  tain.** an Engli
1cb40 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63  sh language desc
1cb50 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65  ription of the e
1cb60 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  rror following a
1cb70 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a   failure of any.
1cb80 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
1cb90 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65  3_open() routine
1cba0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  s..**.** ^The de
1cbb0 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
1cbc0 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
1cbd0 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66  will be UTF-8 if
1cbe0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1cbf0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
1cc00 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  en_v2() is calle
1cc10 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20  d and.** UTF-16 
1cc20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
1cc30 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69  te order if sqli
1cc40 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20  te3_open16() is 
1cc50 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74  used..**.** Whet
1cc60 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72  her or not an er
1cc70 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20  ror occurs when 
1cc80 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65  it is opened, re
1cc90 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63  sources.** assoc
1cca0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
1ccb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1ccc0 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75  ion] handle shou
1ccd0 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ld be released b
1cce0 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20  y.** passing it 
1ccf0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
1cd00 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20  e()] when it is 
1cd10 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72  no longer requir
1cd20 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
1cd30 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1cd40 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20  interface works 
1cd50 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65  like sqlite3_ope
1cd60 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
1cd70 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77  at it accepts tw
1cd80 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72  o additional par
1cd90 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69  ameters for addi
1cda0 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a  tional control.*
1cdb0 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64  * over the new d
1cdc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1cdd0 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73  on.  ^(The flags
1cde0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
1cdf0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1ce00 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20  () can take one 
1ce10 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
1ce20 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73  ing three values
1ce30 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  , optionally com
1ce40 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a  bined with the .
1ce50 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1ce60 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  NOMUTEX], [SQLIT
1ce70 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
1ce80 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
1ce90 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a  SHAREDCACHE],.**
1cea0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
1ceb0 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64  IVATECACHE], and
1cec0 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  /or [SQLITE_OPEN
1ced0 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a  _URI] flags:)^.*
1cee0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c  *.** <dl>.** ^(<
1cef0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
1cf00 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a  READONLY]</dt>.*
1cf10 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
1cf20 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  se is opened in 
1cf30 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20  read-only mode. 
1cf40 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
1cf50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72   does not.** alr
1cf60 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65  eady exist, an e
1cf70 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
1cf80 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1cf90 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
1cfa0 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74  N_READWRITE]</dt
1cfb0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1cfc0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1cfd0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
1cfe0 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
1cff0 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a  ble, or reading.
1d000 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66  ** only if the f
1d010 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
1d020 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
1d030 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
1d040 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61   In either.** ca
1d050 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
1d060 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
1d070 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  st, otherwise an
1d080 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
1d090 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
1d0a0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
1d0b0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
1d0c0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
1d0d0 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  EATE]</dt>.** <d
1d0e0 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1d0f0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
1d100 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
1d110 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64  , and is created
1d120 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e   if.** it does n
1d130 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ot already exist
1d140 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65  . This is the be
1d150 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61  havior that is a
1d160 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a  lways used for.*
1d170 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1d180 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1d190 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  n16().</dd>)^.**
1d1a0 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </dl>.**.** If 
1d1b0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
1d1c0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
1d1d0 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e  n_v2() is not on
1d1e0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62  e of the.** comb
1d1f0 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
1d200 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  bove optionally 
1d210 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74  combined with ot
1d220 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  her.** [SQLITE_O
1d230 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53  PEN_READONLY | S
1d240 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74  QLITE_OPEN_* bit
1d250 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  s].** then the b
1d260 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
1d270 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ined..**.** ^If 
1d280 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
1d290 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  _NOMUTEX] flag i
1d2a0 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20  s set, then the 
1d2b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d2c0 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20  ion.** opens in 
1d2d0 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  the multi-thread
1d2e0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
1d2f0 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  ] as long as the
1d300 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a   single-thread.*
1d310 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62  * mode has not b
1d320 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69  een set at compi
1d330 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
1d340 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a  -time.  ^If the.
1d350 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1d360 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20  FULLMUTEX] flag 
1d370 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20  is set then the 
1d380 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d390 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20  ion opens.** in 
1d3a0 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
1d3b0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
1d3c0 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68  unless single-th
1d3d0 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76  read was.** prev
1d3e0 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20  iously selected 
1d3f0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
1d400 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a  or start-time..*
1d410 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
1d420 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
1d430 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
1d440 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1d450 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c  tion to be.** el
1d460 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73  igible to use [s
1d470 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
1d480 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ], regardless of
1d490 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1d4a0 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
1d4b0 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  is enabled using
1d4c0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
1d4d0 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d  _shared_cache()]
1d4e0 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49  .  ^The.** [SQLI
1d4f0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
1d500 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
1d510 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
1d520 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74  onnection to not
1d530 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20  .** participate 
1d540 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  in [shared cache
1d550 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69   mode] even if i
1d560 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  t is enabled..**
1d570 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
1d580 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1d590 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1d5a0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1d5b0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
1d5c0 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
1d5d0 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
1d5e0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
1d5f0 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68  rface that.** th
1d600 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
1d610 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
1d620 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66   use.  ^If the f
1d630 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1d640 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  is.** a NULL poi
1d650 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
1d660 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
1d670 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73  fs] object is us
1d680 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
1d690 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a  e filename is ":
1d6a0 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61  memory:", then a
1d6b0 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
1d6c0 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  ary in-memory da
1d6d0 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65  tabase.** is cre
1d6e0 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
1d6f0 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20  nection.  ^This 
1d700 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
1d710 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77  se will vanish w
1d720 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  hen.** the datab
1d730 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
1d740 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72  s closed.  Futur
1d750 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
1d760 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61  Lite might.** ma
1d770 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69  ke use of additi
1d780 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c  onal special fil
1d790 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69  enames that begi
1d7a0 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63  n with the ":" c
1d7b0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20  haracter..** It 
1d7c0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
1d7d0 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62  hat when a datab
1d7e0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74  ase filename act
1d7f0 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e  ually does begin
1d800 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63   with.** a ":" c
1d810 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f  haracter you sho
1d820 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66  uld prefix the f
1d830 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70  ilename with a p
1d840 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a  athname such as.
1d850 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64  ** "./" to avoid
1d860 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a   ambiguity..**.*
1d870 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
1d880 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
1d890 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
1d8a0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
1d8b0 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
1d8c0 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
1d8d0 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69  ated.  ^This pri
1d8e0 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
1d8f0 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
1d900 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
1d910 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
1d920 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d930 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
1d940 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
1d950 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70  es in sqlite3_op
1d960 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46  en()]] <h3>URI F
1d970 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a  ilenames</h3>.**
1d980 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c  .** ^If [URI fil
1d990 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74  ename] interpret
1d9a0 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
1d9b0 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61  , and the filena
1d9c0 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62  me argument.** b
1d9d0 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65  egins with "file
1d9e0 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c  :", then the fil
1d9f0 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72  ename is interpr
1da00 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e  eted as a URI. ^
1da10 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  URI.** filename 
1da20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
1da30 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
1da40 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
1da50 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65  I] flag is.** se
1da60 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20  t in the fourth 
1da70 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
1da80 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f  te3_open_v2(), o
1da90 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62  r if it has.** b
1daa0 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62  een enabled glob
1dab0 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b  ally using the [
1dac0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
1dad0 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74  I] option with t
1dae0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
1daf0 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20  onfig()] method 
1db00 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  or by the [SQLIT
1db10 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69  E_USE_URI] compi
1db20 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a  le-time option..
1db30 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20  ** As of SQLite 
1db40 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55  version 3.7.7, U
1db50 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  RI filename inte
1db60 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75  rpretation is tu
1db70 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64  rned off.** by d
1db80 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75  efault, but futu
1db90 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
1dba0 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62  QLite might enab
1dbb0 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a  le URI filename.
1dbc0 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  ** interpretatio
1dbd0 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53  n by default.  S
1dbe0 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ee "[URI filenam
1dbf0 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f  es]" for additio
1dc00 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
1dc10 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69  on..**.** URI fi
1dc20 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73  lenames are pars
1dc30 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  ed according to 
1dc40 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68  RFC 3986. ^If th
1dc50 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61  e URI contains a
1dc60 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20  n.** authority, 
1dc70 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20  then it must be 
1dc80 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20  either an empty 
1dc90 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74  string or the st
1dca0 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68  ring .** "localh
1dcb0 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75  ost". ^If the au
1dcc0 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61  thority is not a
1dcd0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
1dce0 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61  r "localhost", a
1dcf0 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72  n .** error is r
1dd00 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63  eturned to the c
1dd10 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67  aller. ^The frag
1dd20 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  ment component o
1dd30 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20  f a URI, if .** 
1dd40 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f  present, is igno
1dd50 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  red..**.** ^SQLi
1dd60 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68  te uses the path
1dd70 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68   component of th
1dd80 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d  e URI as the nam
1dd90 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69  e of the disk fi
1dda0 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74  le.** which cont
1ddb0 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73  ains the databas
1ddc0 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  e. ^If the path 
1ddd0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f  begins with a '/
1dde0 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a  ' character, .**
1ddf0 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65   then it is inte
1de00 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62  rpreted as an ab
1de10 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66  solute path. ^If
1de20 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e   the path does n
1de30 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74  ot begin .** wit
1de40 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67  h a '/' (meaning
1de50 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
1de60 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f  ity section is o
1de70 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
1de80 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  URI).** then the
1de90 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72   path is interpr
1dea0 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69  eted as a relati
1deb0 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e  ve path. .** ^On
1dec0 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69   windows, the fi
1ded0 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  rst component of
1dee0 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
1def0 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65  h .** is a drive
1df00 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28   specification (
1df10 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a  e.g. "C:")..**.*
1df20 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65  * [[core URI que
1df30 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a  ry parameters]].
1df40 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d  ** The query com
1df50 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
1df60 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61  may contain para
1df70 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20  meters that are 
1df80 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65  interpreted.** e
1df90 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20  ither by SQLite 
1dfa0 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20  itself, or by a 
1dfb0 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46  [VFS | custom VF
1dfc0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
1dfd0 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  ]..** SQLite int
1dfe0 65 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c 6c  erprets the foll
1dff0 6f 77 69 6e 67 20 74 68 72 65 65 20 71 75 65 72  owing three quer
1e000 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a  y parameters:.**
1e010 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
1e020 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e  i> <b>vfs</b>: ^
1e030 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65  The "vfs" parame
1e040 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20  ter may be used 
1e050 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e  to specify the n
1e060 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20  ame of.**     a 
1e070 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20  VFS object that 
1e080 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65  provides the ope
1e090 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
1e0a0 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f  terface that sho
1e0b0 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73  uld.**     be us
1e0c0 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ed to access the
1e0d0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f   database file o
1e0e0 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73  n disk. ^If this
1e0f0 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
1e100 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74  o.**     an empt
1e110 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66  y string the def
1e120 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20  ault VFS object 
1e130 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66  is used. ^Specif
1e140 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a  ying an unknown.
1e150 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e  **     VFS is an
1e160 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69   error. ^If sqli
1e170 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1e180 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66   used and the vf
1e190 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  s option is.**  
1e1a0 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e     present, then
1e1b0 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69   the VFS specifi
1e1c0 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e  ed by the option
1e1d0 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63   takes precedenc
1e1e0 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68  e over.**     th
1e1f0 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
1e200 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  s the fourth par
1e210 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1e220 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
1e230 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64  **   <li> <b>mod
1e240 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64  e</b>: ^(The mod
1e250 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
1e260 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
1e270 20 22 72 6f 22 2c 20 22 72 77 22 20 6f 72 0a 2a   "ro", "rw" or.*
1e280 2a 20 20 20 20 20 22 72 77 63 22 2e 20 41 74 74  *     "rwc". Att
1e290 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69  empting to set i
1e2a0 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76  t to any other v
1e2b0 61 6c 75 65 20 69 73 20 61 6e 20 65 72 72 6f 72  alue is an error
1e2c0 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20  )^. .**     ^If 
1e2d0 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65  "ro" is specifie
1e2e0 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  d, then the data
1e2f0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
1e300 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a  or read-only .**
1e310 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73       access, jus
1e320 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c  t as if the [SQL
1e330 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
1e340 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e  Y] flag had been
1e350 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20   set in the .** 
1e360 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65      third argume
1e370 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72  nt to sqlite3_pr
1e380 65 70 61 72 65 5f 76 32 28 29 2e 20 5e 49 66 20  epare_v2(). ^If 
1e390 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
1e3a0 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20  is set to .**   
1e3b0 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65    "rw", then the
1e3c0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1e3d0 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69  ned for read-wri
1e3e0 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61  te (but not crea
1e3f0 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  te) .**     acce
1e400 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45  ss, as if SQLITE
1e410 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
1e420 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f  (but not SQLITE_
1e430 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64  OPEN_CREATE) had
1e440 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65   .**     been se
1e450 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20  t. ^Value "rwc" 
1e460 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
1e470 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a   setting both .*
1e480 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
1e490 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20  N_READWRITE and 
1e4a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
1e4b0 54 45 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  TE. ^If sqlite3_
1e4c0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 0a 2a 2a  open_v2() is .**
1e4d0 20 20 20 20 20 75 73 65 64 2c 20 69 74 20 69 73       used, it is
1e4e0 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65   an error to spe
1e4f0 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72  cify a value for
1e500 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65   the mode parame
1e510 74 65 72 20 74 68 61 74 20 69 73 20 0a 2a 2a 20  ter that is .** 
1e520 20 20 20 20 6c 65 73 73 20 72 65 73 74 72 69 63      less restric
1e530 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73  tive than that s
1e540 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
1e550 66 6c 61 67 73 20 70 61 73 73 65 64 20 61 73 20  flags passed as 
1e560 74 68 65 20 74 68 69 72 64 20 0a 2a 2a 20 20 20  the third .**   
1e570 20 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a    parameter..**.
1e580 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63  **   <li> <b>cac
1e590 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63  he</b>: ^The cac
1e5a0 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
1e5b0 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
1e5c0 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a  r "shared" or.**
1e5d0 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20       "private". 
1e5e0 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22  ^Setting it to "
1e5f0 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76  shared" is equiv
1e600 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
1e610 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49   the.**     SQLI
1e620 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1e630 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66  CHE bit in the f
1e640 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61  lags argument pa
1e650 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73  ssed to.**     s
1e660 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1e670 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63  . ^Setting the c
1e680 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74  ache parameter t
1e690 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a  o "private" is .
1e6a0 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e  **     equivalen
1e6b0 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
1e6c0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
1e6d0 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a  VATECACHE bit..*
1e6e0 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65  *     ^If sqlite
1e6f0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
1e700 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63  sed and the "cac
1e710 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73  he" parameter is
1e720 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20   present in.**  
1e730 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d     a URI filenam
1e740 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65  e, its value ove
1e750 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76  rrides any behav
1e760 69 6f 75 72 20 72 65 71 75 65 73 74 65 64 20 62  iour requested b
1e770 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20  y setting.**    
1e780 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
1e790 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c  VATECACHE or SQL
1e7a0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
1e7b0 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f  ACHE flag..** </
1e7c0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69  ul>.**.** ^Speci
1e7d0 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
1e7e0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
1e7f0 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
1e800 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f  t of a URI is no
1e810 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20  t an.** error.  
1e820 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
1e830 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
1e840 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74  understand addit
1e850 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70  ional query.** p
1e860 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20  arameters.  See 
1e870 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  "[query paramete
1e880 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20  rs with special 
1e890 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74  meaning to SQLit
1e8a0 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74  e]" for.** addit
1e8b0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
1e8c0 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  n..**.** [[URI f
1e8d0 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
1e8e0 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e  ]] <h3>URI filen
1e8f0 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33  ame examples</h3
1e900 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  >.**.** <table b
1e910 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d  order="1" align=
1e920 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69  center cellpaddi
1e930 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ng=5>.** <tr><th
1e940 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  > URI filenames 
1e950 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20  <th> Results.** 
1e960 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
1e970 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
1e980 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
1e990 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
1e9a0 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
1e9b0 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72  irectory..** <tr
1e9c0 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
1e9d0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72  /fred/data.db<br
1e9e0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  >.**          fi
1e9f0 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f  le:///home/fred/
1ea00 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a  data.db <br> .**
1ea10 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
1ea20 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f  /localhost/home/
1ea30 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
1ea40 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  > <td> .**      
1ea50 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74      Open the dat
1ea60 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d  abase file "/hom
1ea70 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
1ea80 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
1ea90 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d  e://darkstar/hom
1eaa0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
1eab0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
1eac0 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b   An error. "dark
1ead0 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72  star" is not a r
1eae0 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72  ecognized author
1eaf0 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20  ity..** <tr><td 
1eb00 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61  style="white-spa
1eb10 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20  ce:nowrap"> .** 
1eb20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
1eb30 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30  /C:/Documents%20
1eb40 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66  and%20Settings/f
1eb50 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61  red/Desktop/data
1eb60 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20  .db.**     <td> 
1eb70 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70  Windows only: Op
1eb80 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
1eb90 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20  a.db" on fred's 
1eba0 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65  desktop on drive
1ebb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e  .**          C:.
1ebc0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25   Note that the %
1ebd0 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74  20 escaping in t
1ebe0 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e  his example is n
1ebf0 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20  ot strictly .** 
1ec00 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61           necessa
1ec10 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61  ry - space chara
1ec20 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65  cters can be use
1ec30 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20  d literally.**  
1ec40 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66          in URI f
1ec50 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72  ilenames..** <tr
1ec60 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
1ec70 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65  db?mode=ro&cache
1ec80 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a  =private <td> .*
1ec90 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
1eca0 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
1ecb0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
1ecc0 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64  rectory for read
1ecd0 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a  -only access..**
1ece0 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64            Regard
1ecf0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
1ed00 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61  or not shared-ca
1ed10 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62  che mode is enab
1ed20 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  led by.**       
1ed30 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20     default, use 
1ed40 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e  a private cache.
1ed50 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
1ed60 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
1ed70 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f  a.db?vfs=unix-no
1ed80 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20  lock <td>.**    
1ed90 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
1eda0 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
1edb0 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70  .db". Use the sp
1edc0 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d  ecial VFS "unix-
1edd0 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e  nolock"..** <tr>
1ede0 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
1edf0 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20  b?mode=readonly 
1ee00 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
1ee10 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61    An error. "rea
1ee20 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20  donly" is not a 
1ee30 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72  valid option for
1ee40 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61   the "mode" para
1ee50 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c  meter..** </tabl
1ee60 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65  e>.**.** ^URI he
1ee70 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
1ee80 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29   sequences (%HH)
1ee90 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77   are supported w
1eea0 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61  ithin the path a
1eeb0 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70  nd.** query comp
1eec0 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e  onents of a URI.
1eed0 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65   A hexadecimal e
1eee0 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63  scape sequence c
1eef0 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20  onsists of a.** 
1ef00 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22  percent sign - "
1ef10 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79  %" - followed by
1ef20 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78   exactly two hex
1ef30 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20  adecimal digits 
1ef40 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61  .** specifying a
1ef50 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e  n octet value. ^
1ef60 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20  Before the path 
1ef70 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  or query compone
1ef80 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20  nts of a.** URI 
1ef90 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74  filename are int
1efa0 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61  erpreted, they a
1efb0 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  re encoded using
1efc0 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a   UTF-8 and all .
1efd0 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  ** hexadecimal e
1efe0 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
1eff0 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69  replaced by a si
1f000 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69  ngle byte contai
1f010 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72  ning the.** corr
1f020 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e  esponding octet.
1f030 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73   If this process
1f040 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e   generates an in
1f050 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f  valid UTF-8 enco
1f060 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73  ding,.** the res
1f070 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
1f080 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
1f090 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65  e to Windows use
1f0a0 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
1f0b0 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
1f0c0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
1f0d0 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  ment.** of sqlit
1f0e0 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
1f0f0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1f100 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e  must be UTF-8, n
1f110 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63  ot whatever.** c
1f120 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65  odepage is curre
1f130 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46  ntly defined.  F
1f140 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e  ilenames contain
1f150 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61  ing internationa
1f160 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  l.** characters 
1f170 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
1f180 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72  d to UTF-8 prior
1f190 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d   to passing them
1f1a0 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
1f1b0 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
1f1c0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f  e3_open_v2()..*/
1f1d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
1f1e0 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
1f1f0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
1f200 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
1f210 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
1f220 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
1f230 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
1f240 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
1f250 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1f260 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73  3_open16(.  cons
1f270 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
1f280 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1f290 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36  filename (UTF-16
1f2a0 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
1f2b0 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
1f2c0 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
1f2d0 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
1f2e0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  t sqlite3_open_v
1f2f0 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  2(.  const char 
1f300 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
1f310 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
1f320 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
1f330 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20  qlite3 **ppDb,  
1f340 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
1f350 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
1f360 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20  */.  int flags, 
1f370 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1f380 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74  Flags */.  const
1f390 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20   char *zVfs     
1f3a0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46     /* Name of VF
1f3b0 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20  S module to use 
1f3c0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
1f3d0 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61  I3REF: Obtain Va
1f3e0 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72  lues For URI Par
1f3f0 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68  ameters.**.** Th
1f400 69 73 20 69 73 20 61 20 75 74 69 6c 69 74 79 20  is is a utility 
1f410 72 6f 75 74 69 6e 65 2c 20 75 73 65 66 75 6c 20  routine, useful 
1f420 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
1f430 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
1f440 63 6b 73 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66  cks.** to see if
1f450 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
1f460 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20   was a URI that 
1f470 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63  contained a spec
1f480 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70  ific query .** p
1f490 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66  arameter, and if
1f4a0 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20   so obtains the 
1f4b0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 71 75 65  value of the que
1f4c0 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
1f4d0 0a 2a 2a 20 54 68 65 20 7a 46 69 6c 65 6e 61 6d  .** The zFilenam
1f4e0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  e argument is th
1f4f0 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74  e filename point
1f500 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  er passed into t
1f510 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 6d 65  he xOpen().** me
1f520 74 68 6f 64 20 6f 66 20 61 20 56 46 53 20 69 6d  thod of a VFS im
1f530 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
1f540 68 65 20 7a 50 61 72 61 6d 20 61 72 67 75 6d 65  he zParam argume
1f550 6e 74 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  nt is the name o
1f560 66 20 74 68 65 0a 2a 2a 20 71 75 65 72 79 20 70  f the.** query p
1f570 61 72 61 6d 65 74 65 72 20 77 65 20 73 65 65 6b  arameter we seek
1f580 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  .  This routine 
1f590 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
1f5a0 65 20 6f 66 20 74 68 65 20 7a 50 61 72 61 6d 0a  e of the zParam.
1f5b0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20  ** parameter if 
1f5c0 69 74 20 65 78 69 73 74 73 2e 20 20 49 66 20 74  it exists.  If t
1f5d0 68 65 20 70 61 72 61 6d 65 74 65 72 20 64 6f 65  he parameter doe
1f5e0 73 20 6e 6f 74 20 65 78 69 73 74 2c 20 74 68 69  s not exist, thi
1f5f0 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 74  s routine.** ret
1f600 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
1f610 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ter..**.** If th
1f620 65 20 7a 46 69 6c 65 6e 61 6d 65 20 61 72 67 75  e zFilename argu
1f630 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66 75 6e  ment to this fun
1f640 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 20 70  ction is not a p
1f650 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69  ointer that SQLi
1f660 74 65 0a 2a 2a 20 70 61 73 73 65 64 20 69 6e 74  te.** passed int
1f670 6f 20 74 68 65 20 78 4f 70 65 6e 20 56 46 53 20  o the xOpen VFS 
1f680 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65  method, then the
1f690 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69   behavior of thi
1f6a0 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73 20  s routine.** is 
1f6b0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
1f6c0 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
1f6d0 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  le..*/.const cha
1f6e0 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  r *sqlite3_uri_p
1f6f0 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63  arameter(const c
1f700 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20  har *zFilename, 
1f710 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72  const char *zPar
1f720 61 6d 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  am);.../*.** CAP
1f730 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
1f740 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
1f750 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1f760 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74  e3_errcode() int
1f770 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
1f780 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75  he numeric [resu
1f790 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  lt code] or.** [
1f7a0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
1f7b0 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f  code] for the mo
1f7c0 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64  st recent failed
1f7d0 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
1f7e0 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  all.** associate
1f7f0 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  d with a [databa
1f800 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
1f810 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63  If a prior API c
1f820 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75  all failed.** bu
1f830 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
1f840 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65  t API call succe
1f850 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e  eded, the return
1f860 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73   value from.** s
1f870 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1f880 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
1f890 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
1f8a0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a  ended_errcode().
1f8b0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
1f8c0 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20  the same except 
1f8d0 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72  that it always r
1f8e0 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b  eturns the .** [
1f8f0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
1f900 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20  code] even when 
1f910 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
1f920 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73  codes are.** dis
1f930 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
1f940 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
1f950 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
1f960 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
1f970 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
1f980 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
1f990 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
1f9a0 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
1f9b0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
1f9c0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
1f9d0 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
1f9e0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
1f9f0 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
1fa00 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
1fa10 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
1fa20 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
1fa30 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
1fa40 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
1fa50 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
1fa60 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
1fa70 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
1fa80 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
1fa90 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
1faa0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
1fab0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
1fac0 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
1fad0 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  )^.**.** When th
1fae0 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
1faf0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
1fb00 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68   in use, it migh
1fb10 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65  t be the.** case
1fb20 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65   that a second e
1fb30 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61  rror occurs on a
1fb40 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
1fb50 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74   in between.** t
1fb60 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66  he time of the f
1fb70 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74  irst error and t
1fb80 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65  he call to these
1fb90 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
1fba0 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e  When that happen
1fbb0 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72  s, the second er
1fbc0 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f  ror will be repo
1fbd0 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65  rted since these
1fbe0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
1fbf0 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65  lways report the
1fc00 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73   most recent res
1fc10 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a  ult.  To avoid.*
1fc20 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72  * this, each thr
1fc30 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65  ead can obtain e
1fc40 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20  xclusive use of 
1fc50 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
1fc60 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62  nnection] D.** b
1fc70 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  y invoking [sqli
1fc80 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d  te3_mutex_enter]
1fc90 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
1fca0 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62  ex](D)) before b
1fcb0 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75  eginning.** to u
1fcc0 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  se D and invokin
1fcd0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
1fce0 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33  _leave]([sqlite3
1fcf0 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61  _db_mutex](D)) a
1fd00 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c  fter.** all call
1fd10 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61  s to the interfa
1fd20 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20  ces listed here 
1fd30 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a  are completed..*
1fd40 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
1fd50 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
1fd60 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
1fd70 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
1fd80 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
1fd90 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
1fda0 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
1fdb0 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
1fdc0 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
1fdd0 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
1fde0 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
1fdf0 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e  ot be set..*/.in
1fe00 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
1fe10 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
1fe20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
1fe30 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c  nded_errcode(sql
1fe40 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74  ite3 *db);.const
1fe50 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
1fe60 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
1fe70 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
1fe80 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
1fe90 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1fea0 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74  CAPI3REF: SQL St
1feb0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
1fec0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
1fed0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
1fee0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
1fef0 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
1ff00 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
1ff10 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
1ff20 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
1ff30 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68  statement..** Th
1ff40 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72  is object is var
1ff50 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  iously known as 
1ff60 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74  a "prepared stat
1ff70 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22  ement" or a.** "
1ff80 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
1ff90 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c  tement" or simpl
1ffa0 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e  y as a "statemen
1ffb0 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  t"..**.** The li
1ffc0 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e  fe of a statemen
1ffd0 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f  t object goes so
1ffe0 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
1fff0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
20000 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
20010 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
20020 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
20030 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65  2()] or a relate
20040 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69  d.**      functi
20050 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  on..** <li> Bind
20060 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74   values to [host
20070 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69   parameters] usi
20080 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
20090 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
200a0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
200b0 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
200c0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
200d0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
200e0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
200f0 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
20100 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
20110 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
20120 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
20130 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
20140 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
20150 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
20160 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
20170 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
20180 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
20190 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
201a0 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64  **.** Refer to d
201b0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20  ocumentation on 
201c0 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f  individual metho
201d0 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64  ds above for add
201e0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
201f0 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  mation..*/.typed
20200 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
20210 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
20220 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
20230 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
20240 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  imits.**.** ^(Th
20250 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
20260 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
20270 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
20280 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
20290 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
202a0 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
202b0 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
202c0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
202d0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
202e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
202f0 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
20300 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
20310 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
20320 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
20330 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
20340 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
20350 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
20360 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
20370 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
20380 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
20390 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
203a0 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
203b0 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
203c0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t.)^.**.** ^If t
203d0 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
203e0 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
203f0 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
20400 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28  unchanged..** ^(
20410 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63  For each limit c
20420 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c  ategory SQLITE_L
20430 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  IMIT_<i>NAME</i>
20440 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20   there is a .** 
20450 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75  [limits | hard u
20460 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73  pper bound].** s
20470 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
20480 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f  me by a C prepro
20490 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c  cessor macro cal
204a0 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c  led.** [limits |
204b0 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e   SQLITE_MAX_<i>N
204c0 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68  AME</i>]..** (Th
204d0 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74  e "_LIMIT_" in t
204e0 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67  he name is chang
204f0 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29  ed to "_MAX_".))
20500 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74  ^.** ^Attempts t
20510 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d  o increase a lim
20520 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72  it above its har
20530 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72  d upper bound ar
20540 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72  e.** silently tr
20550 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68  uncated to the h
20560 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e  ard upper bound.
20570 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65  .**.** ^Regardle
20580 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
20590 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77   not the limit w
205a0 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20  as changed, the 
205b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  .** [sqlite3_lim
205c0 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  it()] interface 
205d0 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f  returns the prio
205e0 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c  r value of the l
205f0 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c  imit..** ^Hence,
20600 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72   to find the cur
20610 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20  rent value of a 
20620 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68  limit without ch
20630 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69  anging it,.** si
20640 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73  mply invoke this
20650 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20   interface with 
20660 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
20670 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a  ter set to -1..*
20680 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69  *.** Run-time li
20690 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
206a0 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
206b0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
206c0 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
206d0 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
206e0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
206f0 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
20700 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
20710 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
20720 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
20730 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
20740 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
20750 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f   be a.** web bro
20760 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
20770 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
20780 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
20790 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
207a0 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
207b0 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
207c0 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
207d0 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
207e0 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
207f0 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
20800 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
20810 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
20820 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
20830 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
20840 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
20850 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
20860 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
20870 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
20880 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
20890 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
208a0 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
208b0 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ack.  Developers
208c0 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
208d0 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
208e0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
208f0 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
20900 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
20910 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
20920 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
20930 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
20940 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
20950 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
20960 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
20970 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
20980 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
20990 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
209a0 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69   New run-time li
209b0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d  mit categories m
209c0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
209d0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
209e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
209f0 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
20a00 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
20a10 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
20a20 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
20a30 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a  mit Categories.*
20a40 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
20a50 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c  it category} {*l
20a60 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
20a70 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
20a80 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
20a90 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
20aa0 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
20ab0 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
20ac0 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
20ad0 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
20ae0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
20af0 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
20b00 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
20b10 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
20b20 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
20b30 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
20b40 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
20b50 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
20b60 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
20b70 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
20b80 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
20b90 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
20ba0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
20bb0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
20bc0 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
20bd0 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
20be0 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
20bf0 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e  w, in bytes.<dd>
20c00 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
20c10 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
20c20 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
20c30 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
20c40 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
20c50 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
20c60 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
20c70 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
20c80 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
20c90 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
20ca0 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  UMN]] ^(<dt>SQLI
20cb0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
20cc0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
20cd0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
20ce0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
20cf0 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
20d00 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
20d10 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
20d20 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
20d30 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
20d40 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
20d50 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
20d60 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
20d70 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
20d80 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
20d90 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
20da0 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
20db0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
20dc0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
20dd0 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
20de0 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
20df0 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
20e00 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  sion.</dd>)^.**.
20e10 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
20e20 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
20e30 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
20e40 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
20e50 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
20e60 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
20e70 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
20e80 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
20e90 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
20ea0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
20eb0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
20ec0 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  OP]] ^(<dt>SQLIT
20ed0 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
20ee0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
20ef0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
20f00 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
20f10 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
20f20 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
20f30 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
20f40 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
20f50 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69  t.  This limit i
20f60 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a  s not currently.
20f70 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f  ** enforced, tho
20f80 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62  ugh that might b
20f90 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20  e added in some 
20fa0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
20fb0 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64  f.** SQLite.</dd
20fc0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
20fd0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
20fe0 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51  N_ARG]] ^(<dt>SQ
20ff0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
21000 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
21010 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
21020 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
21030 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
21040 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
21050 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  [[SQLITE_LIMIT_A
21060 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e  TTACHED]] ^(<dt>
21070 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
21080 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
21090 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
210a0 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
210b0 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
210c0 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  ases].)^</dd>.**
210d0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
210e0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
210f0 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64  LENGTH]].** ^(<d
21100 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
21110 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
21120 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
21130 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
21140 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e  h of the pattern
21150 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
21160 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47   [LIKE] or.** [G
21170 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c  LOB] operators.<
21180 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
21190 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
211a0 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a  ABLE_NUMBER]].**
211b0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
211c0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
211d0 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
211e0 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65  The maximum inde
211f0 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20  x number of any 
21200 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61  [parameter] in a
21210 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
21220 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
21230 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
21240 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
21250 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
21260 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
21270 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
21280 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
21290 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
212a0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
212b0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
212c0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
212d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
212e0 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
212f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
21300 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
21310 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
21320 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
21330 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
21340 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
21350 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
21360 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
21370 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
21380 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
21390 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
213a0 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
213b0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
213c0 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
213d0 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
213e0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
213f0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
21400 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
21410 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
21420 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
21430 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
21440 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
21450 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
21460 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
21470 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
21480 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
21490 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23  ER           9.#
214a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
214b0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
214c0 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  H            10.
214d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
214e0 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
214f0 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
21500 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
21510 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
21520 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  }.**.** To execu
21530 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
21540 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
21550 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
21560 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
21570 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
21580 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
21590 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
215a0 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
215b0 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
215c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
215d0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
215e0 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
215f0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
21600 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
21610 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
21620 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
21630 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
21640 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21650 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
21660 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
21670 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
21680 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
21690 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
216a0 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
216b0 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
216c0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
216d0 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
216e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
216f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
21700 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
21710 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
21720 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
21730 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
21740 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
21750 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
21760 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
21770 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
21780 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
21790 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ro, then zSql is
217a0 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
217b0 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
217c0 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
217d0 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
217e0 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
217f0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e  the maximum.** n
21800 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20  umber of  bytes 
21810 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
21820 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20   ^When nByte is 
21830 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
21840 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67  e.** zSql string
21850 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20   ends at either 
21860 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27  the first '\000'
21870 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61   or '\u0000' cha
21880 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65  racter or.** the
21890 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20   nByte-th byte, 
218a0 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
218b0 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61  first. If the ca
218c0 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68  ller knows.** th
218d0 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
218e0 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
218f0 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74  rminated, then t
21900 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a  here is a small.
21910 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ** performance a
21920 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67  dvantage to be g
21930 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67  ained by passing
21940 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65   an nByte parame
21950 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65  ter that.** is e
21960 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62  qual to the numb
21970 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
21980 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
21990 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
219a0 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
219b0 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73 20  inator bytes as 
219c0 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69 74  this saves SQLit
219d0 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f  e from having to
219e0 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  .** make a copy 
219f0 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  of the input str
21a00 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70  ing..**.** ^If p
21a10 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c  zTail is not NUL
21a20 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  L then *pzTail i
21a30 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
21a40 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74  to the first byt
21a50 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e  e.** past the en
21a60 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53  d of the first S
21a70 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
21a80 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75  zSql.  These rou
21a90 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f  tines only.** co
21aa0 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20  mpile the first 
21ab0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
21ac0 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
21ad0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
21ae0 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e  o.** what remain
21af0 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  s uncompiled..**
21b00 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20  .** ^*ppStmt is 
21b10 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
21b20 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
21b30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
21b40 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
21b50 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
21b60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
21b70 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61    ^If there is a
21b80 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74  n error, *ppStmt
21b90 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55   is set.** to NU
21ba0 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70  LL.  ^If the inp
21bb0 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
21bc0 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
21bd0 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74  input is an empt
21be0 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61  y.** string or a
21bf0 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
21c00 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
21c10 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61   NULL..** The ca
21c20 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20  lling procedure 
21c30 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
21c40 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  or deleting the 
21c50 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20  compiled.** SQL 
21c60 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
21c70 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
21c80 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61  e()] after it ha
21c90 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
21ca0 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61  it..** ppStmt ma
21cb0 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a  y not be NULL..*
21cc0 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73  *.** ^On success
21cd0 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72  , the sqlite3_pr
21ce0 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f  epare() family o
21cf0 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  f routines retur
21d00 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a  n [SQLITE_OK];.*
21d10 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b  * otherwise an [
21d20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
21d30 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
21d40 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
21d50 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69  re_v2() and sqli
21d60 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
21d70 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  () interfaces ar
21d80 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e.** recommended
21d90 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f   for all new pro
21da0 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f  grams. The two o
21db0 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
21dc0 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20  are retained.** 
21dd0 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
21de0 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
21df0 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
21e00 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49  scouraged..** ^I
21e10 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
21e20 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61  faces, the prepa
21e30 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
21e40 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65   that is returne
21e50 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
21e60 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f  stmt] object) co
21e70 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66  ntains a copy of
21e80 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   the.** original
21e90 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
21ea0 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
21eb0 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
21ec0 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
21ed0 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69  ve differently i
21ee0 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a  n three ways:.**
21ef0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
21f00 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61  .** ^If the data
21f10 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
21f20 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20  ges, instead of 
21f30 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
21f40 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a  E_SCHEMA] as it.
21f50 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74  ** always used t
21f60 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73  o do, [sqlite3_s
21f70 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f  tep()] will auto
21f80 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
21f90 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73  ile the SQL.** s
21fa0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79  tatement and try
21fb0 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e   to run it again
21fc0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
21fd0 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61   <li>.** ^When a
21fe0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
21ff0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
22000 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
22010 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
22020 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
22030 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
22040 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54  rror codes].  ^T
22050 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
22060 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
22070 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
22080 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
22090 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
220a0 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
220b0 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68  t code.** and th
220c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f  e application wo
220d0 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
220e0 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
220f0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
22100 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ()].** in order 
22110 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
22120 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
22130 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74  the problem. Wit
22140 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61  h the "v2" prepa
22150 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  re.** interfaces
22160 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
22170 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
22180 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
22190 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  d immediately..*
221a0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
221b0 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70  i>.** ^If the sp
221c0 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75  ecific value bou
221d0 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  nd to [parameter
221e0 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65   | host paramete
221f0 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48  r] in the .** WH
22200 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74  ERE clause might
22210 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63   influence the c
22220 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
22230 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d  lan for a statem
22240 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ent,.** then the
22250 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
22260 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
22270 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20   recompiled, as 
22280 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65  if there had bee
22290 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63  n .** a schema c
222a0 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69  hange, on the fi
222b0 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74  rst  [sqlite3_st
222c0 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f  ep()] call follo
222d0 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a  wing any change.
222e0 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
222f0 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62  e3_bind_text | b
22300 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74  indings] of that
22310 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a   [parameter]. .*
22320 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20  * ^The specific 
22330 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63  value of WHERE-c
22340 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72  lause [parameter
22350 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  ] might influenc
22360 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65  e the .** choice
22370 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69   of query plan i
22380 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
22390 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64  is the left-hand
223a0 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45   side of a [LIKE
223b0 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f  ].** or [GLOB] o
223c0 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68  perator or if th
223d0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63  e parameter is c
223e0 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e  ompared to an in
223f0 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  dexed column.** 
22400 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  and the [SQLITE_
22410 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f  ENABLE_STAT3] co
22420 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
22430 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
22440 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a   the .** </li>.*
22450 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ol>.*/.int s
22460 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
22470 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
22480 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
22490 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
224a0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
224b0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
224c0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
224d0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
224e0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
224f0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
22500 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
22510 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
22520 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
22530 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
22540 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
22550 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
22560 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
22570 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
22580 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
22590 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
225a0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
225b0 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
225c0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
225d0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
225e0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
225f0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
22600 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
22610 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
22620 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
22630 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
22640 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
22650 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
22660 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
22670 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
22680 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
22690 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
226a0 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
226b0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
226c0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
226d0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
226e0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
226f0 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
22700 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
22710 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
22720 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
22730 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
22740 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
22750 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
22760 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
22770 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
22780 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
22790 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
227a0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
227b0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
227c0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
227d0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
227e0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
227f0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
22800 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
22810 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
22820 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
22830 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
22840 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
22850 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
22860 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
22870 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
22880 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
22890 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
228a0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
228b0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
228c0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
228d0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
228e0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
228f0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
22900 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
22910 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
22920 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
22930 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
22940 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
22950 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
22960 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
22970 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
22980 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53  EF: Retrieving S
22990 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a  tatement SQL.**.
229a0 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
229b0 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
229c0 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76  o retrieve a sav
229d0 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f  ed copy of the o
229e0 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74  riginal.** SQL t
229f0 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61  ext used to crea
22a00 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
22a10 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61  tatement] if tha
22a20 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a  t statement was.
22a30 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e  ** compiled usin
22a40 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
22a50 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
22a60 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
22a70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  are16_v2()]..*/.
22a80 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
22a90 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  te3_sql(sqlite3_
22aa0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
22ab0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
22ac0 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
22ad0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69  QL Statement Wri
22ae0 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65  tes The Database
22af0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
22b00 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
22b10 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(X) interface r
22b20 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
22b30 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64  -zero) if.** and
22b40 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72   only if the [pr
22b50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22b60 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72  ] X makes no dir
22b70 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a  ect changes to.*
22b80 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
22b90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
22ba0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  le..**.** Note t
22bb0 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  hat [application
22bc0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
22bd0 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76  ctions] or.** [v
22be0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d  irtual tables] m
22bf0 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20  ight change the 
22c00 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63  database indirec
22c10 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66  tly as a side ef
22c20 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72  fect.  .** ^(For
22c30 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20   example, if an 
22c40 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
22c50 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22  nes a function "
22c60 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a  eval()" that .**
22c70 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f   calls [sqlite3_
22c80 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68  exec()], then th
22c90 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20  e following SQL 
22ca0 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a  statement would.
22cb0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ** change the da
22cc0 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f  tabase file thro
22cd0 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73  ugh side-effects
22ce0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
22cf0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
22d00 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c  SELECT eval('DEL
22d10 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52  ETE FROM t1') FR
22d20 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  OM t2;.** </pre>
22d30 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
22d40 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20  .** But because 
22d50 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
22d60 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
22d70 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
22d80 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65  ase file.** dire
22d90 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74  ctly, sqlite3_st
22da0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f  mt_readonly() wo
22db0 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e  uld still return
22dc0 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e   true.)^.**.** ^
22dd0 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  Transaction cont
22de0 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73  rol statements s
22df0 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20  uch as [BEGIN], 
22e00 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42  [COMMIT], [ROLLB
22e10 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f  ACK],.** [SAVEPO
22e20 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41  INT], and [RELEA
22e30 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65  SE] cause sqlite
22e40 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
22e50 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
22e60 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73  ,.** since the s
22e70 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65  tatements themse
22e80 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75  lves do not actu
22e90 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  ally modify the 
22ea0 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20  database but.** 
22eb0 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74  rather they cont
22ec0 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f  rol the timing o
22ed0 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61  f when other sta
22ee0 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74  tements modify t
22ef0 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  he .** database.
22f00 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20    ^The [ATTACH] 
22f10 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61  and [DETACH] sta
22f20 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75  tements also cau
22f30 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  se.** sqlite3_st
22f40 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
22f50 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e   return true sin
22f60 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20  ce, while those 
22f70 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68  statements.** ch
22f80 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75  ange the configu
22f90 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61  ration of a data
22fa0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
22fb0 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b   they do not mak
22fc0 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  e .** changes to
22fd0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
22fe0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
22ff0 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69  es on disk..*/.i
23000 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
23010 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33  readonly(sqlite3
23020 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
23030 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23040 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
23050 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a  d Value Object.*
23060 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
23070 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
23080 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
23090 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
230a0 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
230b0 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
230c0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
230d0 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
230e0 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
230f0 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
23100 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
23110 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
23120 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
23130 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
23140 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73  stores.  ^Values
23150 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
23160 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
23170 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67  .** can be integ
23180 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
23190 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
231a0 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
231b0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
231c0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
231d0 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
231e0 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
231f0 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
23200 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
23210 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
23220 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
23230 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
23240 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
23250 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
23260 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
23270 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
23280 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
23290 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
232a0 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
232b0 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
232c0 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  s specifies.** w
232d0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
232e0 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74   requires a prot
232f0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
23300 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  lue..**.** The t
23310 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22  erms "protected"
23320 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65   and "unprotecte
23330 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74  d" refer to whet
23340 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20  her or not.** a 
23350 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20  mutex is held.  
23360 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65  An internal mute
23370 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
23380 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
23390 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
233a0 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
233b0 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
233c0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
233d0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
233e0 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
233f0 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
23400 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
23410 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
23420 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
23430 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
23440 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
23450 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
23460 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
23470 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
23480 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
23490 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
234a0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
234b0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
234c0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
234d0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
234e0 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
234f0 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
23500 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
23510 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
23520 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
23530 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
23540 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
23550 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
23560 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
23570 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
23580 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
23590 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
235a0 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
235b0 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
235c0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
235d0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
235e0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
235f0 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68   objects even wh
23600 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  en not strictly 
23610 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
23620 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
23630 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
23640 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
23650 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
23660 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
23670 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
23680 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
23690 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
236a0 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68  rotected..** ^Th
236b0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
236c0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
236d0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
236e0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
236f0 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a  s unprotected..*
23700 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71  * Unprotected sq
23710 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
23720 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  cts may only be 
23730 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71  used with.** [sq
23740 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
23750 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
23760 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
23770 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
23780 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73  3_value_blob | s
23790 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
237a0 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  e()] family of.*
237b0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  * interfaces req
237c0 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73  uire protected s
237d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
237e0 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ects..*/.typedef
237f0 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69   struct Mem sqli
23800 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
23810 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
23820 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
23830 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
23840 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
23850 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
23860 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
23870 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
23880 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
23890 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74  bject.  ^A point
238a0 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
238b0 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
238c0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
238d0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
238e0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
238f0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
23900 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
23910 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
23920 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
23930 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
23940 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
23950 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
23960 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
23970 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
23980 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
23990 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
239a0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
239b0 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
239c0 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
239d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
239e0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
239f0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
23a00 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
23a10 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
23a20 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
23a30 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
23a40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
23a50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
23a60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23a70 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
23a80 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
23a90 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ments.** KEYWORD
23aa0 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
23ab0 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
23ac0 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
23ad0 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
23ae0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
23af0 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
23b00 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
23b10 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
23b20 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c  .** ^(In the SQL
23b30 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
23b40 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
23b50 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
23b60 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
23b70 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
23b80 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
23b90 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74   a [parameter] t
23ba0 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20  hat matches one 
23bb0 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  of following.** 
23bc0 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a  templates:.**.**
23bd0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
23be0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
23bf0 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
23c00 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
23c10 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
23c20 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74  >.**.** In the t
23c30 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20  emplates above, 
23c40 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61  NNN represents a
23c50 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
23c60 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65  l,.** and VVV re
23c70 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68  presents an alph
23c80 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66  anumeric identif
23c90 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c  ier.)^  ^The val
23ca0 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ues of these.** 
23cb0 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
23cc0 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
23cd0 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f  rameter names" o
23ce0 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
23cf0 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
23d00 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
23d10 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
23d20 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
23d30 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  re..**.** ^The f
23d40 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
23d50 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
23d60 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69  d_*() routines i
23d70 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f  s always.** a po
23d80 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
23d90 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
23da0 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ct returned from
23db0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
23dc0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74  pare_v2()] or it
23dd0 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a  s variants..**.*
23de0 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  * ^The second ar
23df0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
23e00 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70  dex of the SQL p
23e10 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73  arameter to be s
23e20 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  et..** ^The left
23e30 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
23e40 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
23e50 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65  of 1.  ^When the
23e60 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53   same named.** S
23e70 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
23e80 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  used more than o
23e90 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20  nce, second and 
23ea0 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63  subsequent.** oc
23eb0 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74  currences have t
23ec0 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73  he same index as
23ed0 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
23ee0 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69  rence..** ^The i
23ef0 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70  ndex for named p
23f00 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
23f10 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
23f20 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
23f30 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
23f40 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20  index()] API if 
23f50 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69  desired.  ^The i
23f60 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e  ndex.** for "?NN
23f70 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  N" parameters is
23f80 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e   the value of NN
23f90 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76  N..** ^The NNN v
23fa0 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
23fb0 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b  ween 1 and the [
23fc0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
23fd0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53  .** parameter [S
23fe0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
23ff0 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65  ABLE_NUMBER] (de
24000 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
24010 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  )..**.** ^The th
24020 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
24030 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e  the value to bin
24040 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  d to the paramet
24050 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  er..**.** ^(In t
24060 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68  hose routines th
24070 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
24080 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
24090 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
240a0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
240b0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
240c0 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
240d0 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  he value is the.
240e0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e  ** number of <u>
240f0 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65  bytes</u> in the
24100 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20   value, not the 
24110 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
24120 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74  ters.)^.** ^If t
24130 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
24140 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ter is negative,
24150 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   the length of t
24160 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  he string is.** 
24170 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
24180 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69  tes up to the fi
24190 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
241a0 74 6f 72 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e  tor..** If a non
241b0 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68  -negative fourth
241c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
241d0 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65  ovided to sqlite
241e0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a  3_bind_text().**
241f0 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
24200 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e 20 74  _text16() then t
24210 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  hat parameter mu
24220 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
24230 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74  ffset.** where t
24240 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
24250 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73  r would occur as
24260 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e  suming the strin
24270 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65  g were NUL.** te
24280 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
24290 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
242a0 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f   occur at byte o
242b0 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e  ffsets less than
242c0 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f   .** the value o
242d0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
242e0 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20  ameter then the 
242f0 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
24300 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63   value will.** c
24310 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
24320 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c  NULs.  The resul
24330 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
24340 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e   involving strin
24350 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64  gs.** with embed
24360 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
24370 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
24380 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
24390 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
243a0 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
243b0 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e  _bind_text(), an
243c0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e  d.** sqlite3_bin
243d0 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20  d_text16() is a 
243e0 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
243f0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
24400 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
24410 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
24420 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
24430 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73  th it.  ^The des
24440 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
24450 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20  d.** to dispose 
24460 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
24470 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  tring even if th
24480 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  e call to sqlite
24490 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a  3_bind_blob(),.*
244a0 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  * sqlite3_bind_t
244b0 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  ext(), or sqlite
244c0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
244d0 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20  fails.  .** ^If 
244e0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
244f0 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
24500 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
24510 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
24520 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
24530 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
24540 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
24550 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
24560 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
24570 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
24580 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  eed..** ^If the 
24590 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
245a0 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
245b0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
245c0 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
245d0 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
245e0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
245f0 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
24600 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
24610 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
24620 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
24630 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
24640 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
24650 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
24660 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
24670 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
24680 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
24690 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
246a0 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
246b0 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
246c0 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
246d0 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
246e0 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
246f0 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
24700 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
24710 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
24720 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
24730 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
24740 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
24750 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
24760 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
24770 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
24780 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
24790 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
247a0 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
247b0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
247c0 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
247d0 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
247e0 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   BLOB..**.** ^If
247f0 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69   any of the sqli
24800 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
24810 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
24820 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
24830 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20  nter.** for the 
24840 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24850 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70  ent] or with a p
24860 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24870 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b  t for which.** [
24880 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
24890 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  has been called 
248a0 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68  more recently th
248b0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  an [sqlite3_rese
248c0 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  t()],.** then th
248d0 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75  e call will retu
248e0 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  rn [SQLITE_MISUS
248f0 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69  E].  If any sqli
24900 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72  te3_bind_().** r
24910 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64  outine is passed
24920 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
24930 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
24940 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c   been finalized,
24950 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69   the.** result i
24960 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
24970 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c  probably harmful
24980 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67  ..**.** ^Binding
24990 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
249a0 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
249b0 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
249c0 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20  ne..** ^Unbound 
249d0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69  parameters are i
249e0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55  nterpreted as NU
249f0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
24a00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f  qlite3_bind_* ro
24a10 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
24a20 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
24a30 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  cess or an.** [e
24a40 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e  rror code] if an
24a50 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ything goes wron
24a60 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52  g..** ^[SQLITE_R
24a70 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
24a80 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
24a90 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
24aa0 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b  ut of range.  ^[
24ab0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
24ac0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
24ad0 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a  loc() fails..**.
24ae0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
24af0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
24b00 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
24b10 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
24b20 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
24b30 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
24b40 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
24b50 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
24b60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
24b70 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
24b80 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
24b90 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
24ba0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
24bb0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
24bc0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
24bd0 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
24be0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
24bf0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
24c00 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
24c10 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
24c20 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
24c30 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
24c40 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71  3_int64);.int sq
24c50 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
24c60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
24c70 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
24c80 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
24c90 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
24ca0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20  onst char*, int 
24cb0 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
24cc0 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
24cd0 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
24ce0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
24cf0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
24d00 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
24d10 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
24d20 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
24d30 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
24d40 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
24d50 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
24d60 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
24d70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
24d80 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  t, int n);../*.*
24d90 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
24da0 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
24db0 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ters.**.** ^This
24dc0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
24dd0 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
24de0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
24df0 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
24e00 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
24e10 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
24e20 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
24e30 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
24e40 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
24e50 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
24e60 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
24e70 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
24e80 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
24e90 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
24ea0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
24eb0 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
24ec0 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
24ed0 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
24ee0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
24ef0 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
24f00 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
24f10 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
24f20 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
24f30 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
24f40 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
24f50 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
24f60 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
24f70 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
24f80 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
24f90 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
24fa0 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61   the ?NNN form a
24fb0 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
24fc0 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
24fd0 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a   the list.)^.**.
24fe0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
24ff0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
25000 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
25010 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
25020 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
25030 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
25040 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
25050 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
25060 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
25070 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
25080 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
25090 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
250a0 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
250b0 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a  t Parameter.**.*
250c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
250d0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
250e0 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63  me(P,N) interfac
250f0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  e returns.** the
25100 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74   name of the N-t
25110 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  h [SQL parameter
25120 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] in the [prepar
25130 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
25140 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65  .** ^(SQL parame
25150 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
25160 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
25170 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
25180 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20  $AAA".** have a 
25190 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68  name which is th
251a0 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20  e string "?NNN" 
251b0 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
251c0 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
251d0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
251e0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
251f0 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a  , the initial ":
25200 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20  " or "$" or "@" 
25210 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63  or "?".** is inc
25220 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66  luded as part of
25230 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20   the name.)^.** 
25240 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74  ^Parameters of t
25250 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68  he form "?" with
25260 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20  out a following 
25270 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20  integer have no 
25280 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20  name.** and are 
25290 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22  referred to as "
252a0 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e  nameless" or "an
252b0 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65  onymous paramete
252c0 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rs"..**.** ^The 
252d0 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d  first host param
252e0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
252f0 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a  x of 1, not 0..*
25300 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c  *.** ^If the val
25310 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72  ue N is out of r
25320 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e  ange or if the N
25330 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  -th parameter is
25340 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68  .** nameless, th
25350 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  en NULL is retur
25360 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ned.  ^The retur
25370 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  ned string is.**
25380 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38   always in UTF-8
25390 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69   encoding even i
253a0 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61  f the named para
253b0 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69  meter was.** ori
253c0 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65  ginally specifie
253d0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b  d as UTF-16 in [
253e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
253f0 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  6()] or.** [sqli
25400 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
25410 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
25420 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
25430 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
25440 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
25450 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
25460 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
25470 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
25480 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
25490 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  ex()]..*/.const 
254a0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69  char *sqlite3_bi
254b0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
254c0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
254d0 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   int);../*.** CA
254e0 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66  PI3REF: Index Of
254f0 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74   A Parameter Wit
25500 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a  h A Given Name.*
25510 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
25520 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
25530 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
25540 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65   its name.  ^The
25550 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20  .** index value 
25560 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74  returned is suit
25570 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20  able for use as 
25580 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61  the second.** pa
25590 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
255a0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
255b0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20  lite3_bind()].  
255c0 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65  ^A zero.** is re
255d0 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
255e0 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
255f0 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20  is found.  ^The 
25600 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d  parameter.** nam
25610 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20  e must be given 
25620 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66  in UTF-8 even if
25630 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
25640 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70  atement.** was p
25650 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46  repared from UTF
25660 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b  -16 text using [
25670 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
25680 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
25690 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
256a0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
256b0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
256c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
256d0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
256e0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
256f0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
25700 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
25710 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
25720 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
25730 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
25740 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
25750 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
25760 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
25770 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
25780 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
25790 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f  .** ^Contrary to
257a0 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
257b0 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
257c0 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
257d0 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20  ot reset.** the 
257e0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
257f0 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
25800 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
25810 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73  atement]..** ^Us
25820 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
25830 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
25840 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
25850 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
25860 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
25870 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
25880 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
25890 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
258a0 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
258b0 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  t Set.**.** ^Ret
258c0 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
258d0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
258e0 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
258f0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  rned by the.** [
25900 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25910 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69  nt]. ^This routi
25920 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
25930 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a  pStmt is an SQL.
25940 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
25950 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72  t does not retur
25960 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  n data (for exam
25970 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29  ple an [UPDATE])
25980 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
25990 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  : [sqlite3_data_
259a0 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20  count()].*/.int 
259b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
259c0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
259d0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
259e0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
259f0 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
25a00 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult Set.**.** ^
25a10 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
25a20 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61  eturn the name a
25a30 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72  ssigned to a par
25a40 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a  ticular column.*
25a50 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  * in the result 
25a60 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
25a70 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54  ] statement.  ^T
25a80 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
25a90 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
25aa0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
25ab0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
25ac0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
25ad0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
25ae0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
25af0 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
25b00 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
25b10 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
25b20 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
25b30 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  .  ^The first pa
25b40 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
25b50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25b60 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c  nt].** that impl
25b70 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45  ements the [SELE
25b80 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e  CT] statement. ^
25b90 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
25ba0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63  eter is the.** c
25bb0 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e  olumn number.  ^
25bc0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
25bd0 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e  umn is number 0.
25be0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  .**.** ^The retu
25bf0 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
25c00 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
25c10 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
25c20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25c30 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
25c40 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
25c50 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
25c60 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
25c70 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
25c80 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
25c90 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
25ca0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
25cb0 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
25cc0 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
25cd0 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  r until the next
25ce0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
25cf0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
25d00 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
25d10 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20  umn_name16() on 
25d20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
25d30 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  .**.** ^If sqlit
25d40 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
25d50 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
25d60 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
25d70 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
25d80 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
25d90 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
25da0 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
25db0 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
25dc0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
25dd0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
25de0 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73  he name of a res
25df0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  ult column is th
25e00 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22  e value of the "
25e10 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a  AS" clause for.*
25e20 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69  * that column, i
25e30 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53  f there is an AS
25e40 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65   clause.  If the
25e50 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75  re is no AS clau
25e60 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e  se.** then the n
25e70 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  ame of the colum
25e80 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64  n is unspecified
25e90 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20   and may change 
25ea0 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65  from.** one rele
25eb0 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f  ase of SQLite to
25ec0 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f   the next..*/.co
25ed0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
25ee0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71  3_column_name(sq
25ef0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
25f00 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20   N);.const void 
25f10 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
25f20 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
25f30 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f  tmt*, int N);../
25f40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
25f50 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e  ource Of Data In
25f60 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
25f70 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
25f80 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
25f90 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
25fa0 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c  ne the database,
25fb0 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74   table, and.** t
25fc0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
25fd0 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f   is the origin o
25fe0 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  f a particular r
25ff0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a  esult column in.
26000 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  ** [SELECT] stat
26010 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e  ement..** ^The n
26020 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
26030 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
26040 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
26050 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
26060 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55  her a UTF-8 or U
26070 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
26080 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
26090 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
260a0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
260b0 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
260c0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
260d0 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
260e0 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
260f0 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
26100 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
26110 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ame..** ^The ret
26120 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
26130 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
26140 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26150 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65  ent] is destroye
26160 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
26170 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
26180 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
26190 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
261a0 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
261b0 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
261c0 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
261d0 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
261e0 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
261f0 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
26200 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
26210 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
26220 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
26230 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
26240 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
26250 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
26260 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
26270 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
26280 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
26290 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
262a0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  mn..**.** ^The f
262b0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
262c0 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
262d0 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  s is a [prepared
262e0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
262f0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
26300 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
26310 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
26320 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
26330 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74  returned by.** t
26340 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68  he statement, wh
26350 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
26360 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
26370 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  ument..** ^The l
26380 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
26390 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20  is column 0 for 
263a0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
263b0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74  **.** ^If the Nt
263c0 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
263d0 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
263e0 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
263f0 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65  ion or.** subque
26400 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
26410 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
26420 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
26430 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
26440 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73  .** NULL.  ^Thes
26450 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
26460 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
26470 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
26480 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a  ocation error.**
26490 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72   occurs.  ^Other
264a0 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
264b0 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
264c0 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
264d0 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f  ase, table,.** o
264e0 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  r column that qu
264f0 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
26500 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
26510 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  from..**.** ^As 
26520 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53  with all other S
26530 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73  QLite APIs, thos
26540 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e  e whose names en
26550 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
26560 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
26570 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64  oded strings and
26580 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74   the other funct
26590 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d  ions return UTF-
265a0 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  8..**.** ^These 
265b0 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76  APIs are only av
265c0 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
265d0 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
265e0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
265f0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
26600 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
26610 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
26620 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ymbol..**.** If 
26630 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
26640 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
26650 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f  more of these ro
26660 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74  utines against t
26670 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61  he same.** prepa
26680 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
26690 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20  d column at the 
266a0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
266b0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a  he results are.*
266c0 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
266d0 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
266e0 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
266f0 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73  ne or more.** [s
26700 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
26710 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f  tabase_name | co
26720 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e  lumn metadata in
26730 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72  terfaces].** for
26740 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61   the same [prepa
26750 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
26760 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  nd result column
26770 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20  .** at the same 
26780 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
26790 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
267a0 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ned..*/.const ch
267b0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
267c0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
267d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
267e0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
267f0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
26800 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
26810 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
26820 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
26830 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
26840 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
26850 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
26860 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
26870 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
26880 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
26890 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
268a0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
268b0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
268c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
268d0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
268e0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
268f0 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
26900 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
26910 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
26920 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
26930 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
26940 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54  Result.**.** ^(T
26950 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
26960 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
26970 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
26980 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
26990 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
269a0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
269b0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
269c0 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
269d0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
269e0 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
269f0 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
26a00 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
26a10 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
26a20 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
26a30 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
26a40 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
26a50 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20  is returned.)^  
26a60 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
26a70 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
26a80 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
26a90 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
26aa0 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
26ab0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
26ac0 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72  urned..** ^The r
26ad0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
26ae0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
26af0 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ncoded..**.** ^(
26b00 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
26b10 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
26b20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
26b30 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
26b40 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
26b50 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
26b60 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
26b70 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
26b80 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
26b90 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
26ba0 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
26bb0 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
26bc0 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
26bd0 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
26be0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
26bf0 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
26c00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
26c10 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
26c20 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
26c30 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
26c40 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
26c50 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
26c60 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73   ^So just becaus
26c70 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
26c80 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
26c90 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
26ca0 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
26cb0 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
26cc0 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
26cd0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
26ce0 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
26cf0 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
26d00 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
26d10 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
26d20 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
26d30 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a   static.  ^Type.
26d40 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
26d50 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
26d60 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
26d70 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
26d80 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
26d90 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
26da0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
26db0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
26dc0 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  ltype(sqlite3_st
26dd0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
26de0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
26df0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
26e00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
26e10 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
26e20 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e  REF: Evaluate An
26e30 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
26e40 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72  *.** After a [pr
26e50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26e60 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61  ] has been prepa
26e70 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  red using either
26e80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
26e90 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
26ea0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
26eb0 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
26ec0 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
26ed0 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
26ee0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
26ef0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
26f00 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e  e16()], this fun
26f10 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65  ction.** must be
26f20 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
26f30 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61  ore times to eva
26f40 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  luate the statem
26f50 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
26f60 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
26f70 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71  havior of the sq
26f80 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
26f90 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
26fa0 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
26fb0 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
26fc0 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
26fd0 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65   newer "v2" inte
26fe0 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  rface.** [sqlite
26ff0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
27000 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
27010 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
27020 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79  the older legacy
27030 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73  .** interface [s
27040 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
27050 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
27060 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68  repare16()].  Th
27070 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20  e use of the.** 
27080 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61  new "v2" interfa
27090 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
270a0 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63  d for new applic
270b0 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c  ations but the l
270c0 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
270d0 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65  ce will continue
270e0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
270f0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ..**.** ^In the 
27100 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
27110 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
27120 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
27130 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
27140 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
27150 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
27160 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
27170 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
27180 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  SE]..** ^With th
27190 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
271a0 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
271b0 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  er [result codes
271c0 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
271d0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
271e0 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
271f0 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a  d as well..**.**
27200 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20   ^[SQLITE_BUSY] 
27210 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
27220 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
27230 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
27240 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
27250 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
27260 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
27270 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74  b.  ^If the stat
27280 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d  ement is a [COMM
27290 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  IT].** or occurs
272a0 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
272b0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
272c0 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
272d0 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
272e0 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
272f0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
27300 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e  ot a [COMMIT] an
27310 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  d occurs within 
27320 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74  an.** explicit t
27330 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
27340 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
27350 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
27360 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
27370 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
27380 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d  ^[SQLITE_DONE] m
27390 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
273a0 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
273b0 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
273c0 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
273d0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
273e0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
273f0 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
27400 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
27410 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
27420 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
27430 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
27440 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
27450 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
27460 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
27470 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  l state..**.** ^
27480 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
27490 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75  ment being execu
274a0 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ted returns any 
274b0 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49  data, then [SQLI
274c0 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65  TE_ROW].** is re
274d0 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
274e0 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
274f0 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20  ta is ready for 
27500 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68  processing by th
27510 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65  e.** caller. The
27520 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
27530 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68  ccessed using th
27540 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  e [column access
27550 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
27560 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
27570 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74  s called again t
27580 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e  o retrieve the n
27590 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e  ext row of data.
275a0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
275b0 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
275c0 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
275d0 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
275e0 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
275f0 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
27600 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
27610 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
27620 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
27630 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
27640 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
27650 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
27660 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
27670 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57  errmsg()]..** ^W
27680 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
27690 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
276a0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
276b0 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c  code (for exampl
276c0 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e,.** [SQLITE_IN
276d0 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54  TERRUPT], [SQLIT
276e0 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49  E_SCHEMA], [SQLI
276f0 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64  TE_CORRUPT], and
27700 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61   so forth).** ca
27710 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79  n be obtained by
27720 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
27730 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68  3_reset()] on th
27740 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
27750 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20  tatement].  ^In 
27760 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
27770 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
27780 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
27790 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
277a0 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
277b0 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
277c0 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
277d0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
277e0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
277f0 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
27800 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
27810 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
27820 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
27830 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
27840 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
27850 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
27860 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
27870 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
27880 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
27890 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
278a0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
278b0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
278c0 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
278d0 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
278e0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
278f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
27900 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
27910 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
27920 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
27930 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
27940 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20  ..**.** For all 
27950 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
27960 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63  te up to and inc
27970 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c  luding 3.6.23.1,
27980 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
27990 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
279a0 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74  was required aft
279b0 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  er sqlite3_step(
279c0 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68  ) returned anyth
279d0 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61  ing.** other tha
279e0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62  n [SQLITE_ROW] b
279f0 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71  efore any subseq
27a00 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20  uent invocation 
27a10 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  of.** sqlite3_st
27a20 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74  ep().  Failure t
27a30 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  o reset the prep
27a40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
27a50 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
27a60 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64  3_reset()] would
27a70 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53   result in an [S
27a80 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65  QLITE_MISUSE] re
27a90 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  turn from.** sql
27aa0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75  ite3_step().  Bu
27ab0 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20  t after version 
27ac0 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65  3.6.23.1, sqlite
27ad0 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a  3_step() began.*
27ae0 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * calling [sqlit
27af0 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f  e3_reset()] auto
27b00 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69  matically in thi
27b10 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72  s circumstance r
27b20 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65  ather.** than re
27b30 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
27b40 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69  MISUSE].  This i
27b50 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64  s not considered
27b60 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79   a compatibility
27b70 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73  .** break becaus
27b80 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f  e any applicatio
27b90 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65  n that ever rece
27ba0 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d  ives an SQLITE_M
27bb0 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69  ISUSE error.** i
27bc0 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69  s broken by defi
27bd0 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51  nition.  The [SQ
27be0 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45  LITE_OMIT_AUTORE
27bf0 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  SET] compile-tim
27c00 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20  e option.** can 
27c10 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f  be used to resto
27c20 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  re the legacy be
27c30 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  havior..**.** <b
27c40 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
27c50 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74   Alert:</b> In t
27c60 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
27c70 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ace, the sqlite3
27c80 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61  _step().** API a
27c90 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
27ca0 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f  generic error co
27cb0 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  de, [SQLITE_ERRO
27cc0 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
27cd0 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72  y.** error other
27ce0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55   than [SQLITE_BU
27cf0 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  SY] and [SQLITE_
27d00 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
27d10 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  st call.** [sqli
27d20 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
27d30 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
27d40 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
27d50 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
27d60 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72  .** specific [er
27d70 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ror codes] that 
27d80 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
27d90 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
27da0 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
27db0 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
27dc0 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
27dd0 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
27de0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
27df0 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
27e00 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
27e10 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
27e20 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
27e30 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
27e40 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
27e50 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
27e60 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65  re16_v2()] inste
27e70 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67  ad.** of the leg
27e80 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  acy [sqlite3_pre
27e90 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
27ea0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
27eb0 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a  ] interfaces,.**
27ec0 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73   then the more s
27ed0 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
27ee0 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e  odes] are return
27ef0 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62  ed directly.** b
27f00 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
27f10 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
27f20 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
27f30 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e   is recommended.
27f40 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
27f50 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
27f60 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
27f70 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
27f80 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
27f90 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  ult set.**.** ^T
27fa0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
27fb0 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61  count(P) interfa
27fc0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
27fd0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
27fe0 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   in the.** curre
27ff0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
28000 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65  sult set of [pre
28010 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28020 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61   P..** ^If prepa
28030 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20  red statement P 
28040 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65  does not have re
28050 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72  sults ready to r
28060 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61  eturn.** (via ca
28070 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  lls to the [sqli
28080 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c  te3_column_int |
28090 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
280a0 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  *()] of.** inter
280b0 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69  faces) then sqli
280c0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
280d0 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20  ) returns 0..** 
280e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
280f0 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
28100 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20  ne also returns 
28110 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c  0 if P is a NULL
28120 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68   pointer..** ^Th
28130 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
28140 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
28150 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65  returns 0 if the
28160 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
28170 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
28180 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20  ep](P) returned 
28190 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
281a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
281b0 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69  a_count(P).** wi
281c0 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65  ll return non-ze
281d0 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63  ro if previous c
281e0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
281f0 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
28200 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57  d.** [SQLITE_ROW
28210 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65  ], except in the
28220 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52   case of the [PR
28230 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c  AGMA incremental
28240 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72  _vacuum].** wher
28250 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  e it always retu
28260 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65  rns zero since e
28270 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74  ach step of that
28280 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70   multi-step.** p
28290 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20  ragma returns 0 
282a0 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e  columns of data.
282b0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
282c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
282d0 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74  _count()].*/.int
282e0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
282f0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
28300 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
28310 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
28320 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
28330 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
28340 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
28350 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  ^(Every value in
28360 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
28370 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
28380 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
28390 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
283a0 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
283b0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
283c0 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
283d0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
283e0 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
283f0 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
28400 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
28410 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ul>)^.**.** Thes
28420 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
28430 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
28440 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
28450 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
28460 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
28470 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
28480 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
28490 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
284a0 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
284b0 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
284c0 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
284d0 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
284e0 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
284f0 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
28500 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
28510 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
28520 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  EXT, not.** SQLI
28530 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
28540 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
28550 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
28560 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
28570 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
28580 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
28590 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
285a0 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
285b0 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
285c0 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
285d0 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
285e0 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
285f0 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
28600 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
28610 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
28620 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f  esult Values Fro
28630 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59  m A Query.** KEY
28640 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
28650 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
28660 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
28670 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22  tines form the "
28680 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65  result set" inte
28690 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rface..**.** ^Th
286a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
286b0 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
286c0 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63  about a single c
286d0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
286e0 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72  rent.** result r
286f0 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
28700 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74  ^In every case t
28710 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
28720 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  t is a pointer.*
28730 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  * to the [prepar
28740 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
28750 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c  at is being eval
28760 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
28770 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68  te3_stmt*].** th
28780 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
28790 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72  from [sqlite3_pr
287a0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f  epare_v2()] or o
287b0 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
287c0 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73  ts).** and the s
287d0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
287e0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
287f0 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68  he column for wh
28800 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ich information.
28810 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
28820 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74  urned. ^The left
28830 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  most column of t
28840 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61  he result set ha
28850 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a  s the index 0..*
28860 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  * ^The number of
28870 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
28880 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65  result can be de
28890 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a  termined using.*
288a0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
288b0 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a  n_count()]..**.*
288c0 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
288d0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
288e0 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
288f0 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
28900 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c  or if the.** col
28910 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
28920 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
28930 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
28940 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ed..** These rou
28950 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62  tines may only b
28960 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  e called when th
28970 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
28980 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
28990 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
289a0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
289b0 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a  OW] and neither.
289c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
289d0 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65  t()] nor [sqlite
289e0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61  3_finalize()] ha
289f0 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73  ve been called s
28a00 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
28a10 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
28a20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
28a30 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
28a40 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
28a50 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
28a60 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
28a70 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
28a80 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
28a90 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
28aa0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
28ab0 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
28ac0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
28ad0 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
28ae0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
28af0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
28b00 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
28b10 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
28b20 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
28b30 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
28b40 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
28b50 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
28b60 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
28b70 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
28b80 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
28b90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
28ba0 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ype() routine re
28bb0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51  turns the.** [SQ
28bc0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
28bd0 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
28be0 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
28bf0 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
28c00 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
28c10 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
28c20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
28c30 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
28c40 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
28c50 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
28c60 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
28c70 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
28c80 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
28c90 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
28ca0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
28cb0 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
28cc0 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
28cd0 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
28ce0 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
28cf0 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
28d00 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
28d10 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
28d20 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
28d30 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
28d40 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
28d50 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
28d60 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
28d70 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
28d80 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
28d90 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
28da0 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
28db0 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
28dc0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
28dd0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
28de0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
28df0 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
28e00 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
28e10 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74  _bytes().** rout
28e20 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
28e30 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
28e40 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
28e50 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
28e60 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
28e70 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
28e80 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
28e90 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
28ea0 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
28eb0 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
28ec0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
28ed0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
28ee0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
28ef0 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
28f00 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
28f10 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
28f20 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
28f30 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
28f40 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
28f50 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
28f60 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
28f70 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
28f80 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
28f90 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
28fa0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
28fb0 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
28fc0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
28fd0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
28fe0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
28ff0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
29000 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68  UTF-16 string th
29010 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
29020 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a  olumn_bytes16().
29030 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
29040 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
29050 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
29060 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
29070 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
29080 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
29090 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
290a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
290b0 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
290c0 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
290d0 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  16 and then retu
290e0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
290f0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
29100 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
29110 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
29120 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
29130 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73  n_bytes16() uses
29140 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
29150 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
29160 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
29170 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  o a UTF-16 strin
29180 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
29190 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
291a0 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
291b0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
291c0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
291d0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
291e0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65  umn_bytes16() re
291f0 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
29200 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65  * ^The values re
29210 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
29220 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
29230 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  )] and .** [sqli
29240 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
29250 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63  16()] do not inc
29260 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
29270 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65  rminators at the
29280 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
29290 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61  tring.  ^For cla
292a0 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73  rity: the values
292b0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
292c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
292d0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71  bytes()] and [sq
292e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
292f0 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20  es16()] are the 
29300 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
29310 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
29320 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
29330 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
29340 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72  **.** ^Strings r
29350 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
29360 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
29370 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
29380 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  umn_text16(),.**
29390 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69   even empty stri
293a0 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20  ngs, are always 
293b0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e  zero terminated.
293c0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a    ^The return.**
293d0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
293e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
293f0 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  ) for a zero-len
29400 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55  gth BLOB is a NU
29410 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
29420 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65  * ^The object re
29430 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
29440 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
29450 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70  )] is an.** [unp
29460 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
29470 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20  _value] object. 
29480 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   An unprotected 
29490 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
294a0 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ject.** may only
294b0 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73   be used with [s
294c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
294d0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
294e0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
294f0 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e  ]..** If the [un
29500 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
29510 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
29520 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
29530 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
29540 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20  alue()] is used 
29550 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  in any other way
29560 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c  , including call
29570 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73  s.** to routines
29580 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76   like [sqlite3_v
29590 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
295a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
295b0 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
295c0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
295d0 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  )], then the beh
295e0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
295f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
29600 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
29610 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
29620 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
29630 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a  opriate.  ^For.*
29640 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  * example, if th
29650 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
29660 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
29670 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
29680 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
29690 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
296a0 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
296b0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
296c0 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20   perform the.** 
296d0 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d  conversion autom
296e0 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65  atically.  ^(The
296f0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
29700 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
29710 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74  versions.** that
29720 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
29730 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
29740 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
29750 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
29760 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
29770 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
29780 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
29790 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
297a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
297b0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
297c0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
297d0 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
297e0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
297f0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
29800 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
29810 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
29820 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
29830 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
29840 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
29850 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
29860 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
29870 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
29880 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
29890 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
298a0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
298b0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
298c0 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61   integer to floa
298d0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  t.** <tr><td> IN
298e0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45  TEGER  <td>   TE
298f0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
29900 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
29910 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  e integer.** <tr
29920 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
29930 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
29940 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47  d> Same as INTEG
29950 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  ER->TEXT.** <tr>
29960 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
29970 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
29980 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66  > Convert from f
29990 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a  loat to integer.
299a0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
299b0 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
299c0 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
299d0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
299e0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
299f0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
29a00 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
29a10 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45  ame as FLOAT->TE
29a20 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
29a30 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54  TEXT    <td> INT
29a40 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20  EGER   <td> Use 
29a50 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
29a60 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
29a70 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
29a80 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  Use atof().** <t
29a90 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
29aa0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
29ab0 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
29ac0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
29ad0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
29ae0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
29af0 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
29b00 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
29b10 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
29b20 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
29b30 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20  Convert to TEXT 
29b40 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a  then use atof().
29b50 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
29b60 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  B    <td>   TEXT
29b70 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a      <td> Add a z
29b80 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
29b90 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61  f needed.** </ta
29ba0 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
29bb0 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  uote>)^.**.** Th
29bc0 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61  e table above ma
29bd0 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f  kes reference to
29be0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
29bf0 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74  ary functions at
29c00 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66  oi().** and atof
29c10 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73  ().  SQLite does
29c20 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20   not really use 
29c30 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
29c40 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20    It has its.** 
29c50 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69  own equivalent i
29c60 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73  nternal routines
29c70 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e  .  The atoi() an
29c80 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61  d atof() names a
29c90 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68  re.** used in th
29ca0 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76  e table for brev
29cb0 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20  ity and because 
29cc0 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61  they are familia
29cd0 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70  r to most.** C p
29ce0 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a  rogrammers..**.*
29cf0 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e  * Note that when
29d00 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
29d10 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72  s occur, pointer
29d20 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72  s returned by pr
29d30 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ior.** calls to 
29d40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
29d50 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  lob(), sqlite3_c
29d60 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e  olumn_text(), an
29d70 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
29d80 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
29d90 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74  may be invalidat
29da0 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76  ed..** Type conv
29db0 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e  ersions and poin
29dc0 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e  ter invalidation
29dd0 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
29de0 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
29df0 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  g cases:.**.** <
29e00 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
29e10 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
29e20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71  is a BLOB and sq
29e30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
29e40 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  t() or.**      s
29e50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
29e60 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
29e70 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  .  A zero-termin
29e80 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20  ator might.**   
29e90 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64     need to be ad
29ea0 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e  ded to the strin
29eb0 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  g.</li>.** <li> 
29ec0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
29ed0 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78  ent is UTF-8 tex
29ee0 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
29ef0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f  lumn_bytes16() o
29f00 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
29f10 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
29f20 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
29f30 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
29f40 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
29f50 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f      to UTF-16.</
29f60 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
29f70 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
29f80 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61  is UTF-16 text a
29f90 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
29fa0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
29fb0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
29fc0 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
29fd0 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
29fe0 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
29ff0 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
2a000 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  UTF-8.</li>.** <
2a010 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76  /ul>.**.** ^Conv
2a020 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
2a030 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
2a040 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
2a050 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
2a060 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
2a070 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
2a080 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
2a090 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
2a0a0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
2a0b0 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
2a0c0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65  prior pointer re
2a0d0 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61  ferences will ha
2a0e0 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
2a0f0 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
2a100 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
2a110 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
2a120 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
2a130 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
2a140 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65  imes they.** are
2a150 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
2a160 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
2a170 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
2a180 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
2a190 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
2a1a0 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f  t and easiest to
2a1b0 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79   remember policy
2a1c0 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
2a1d0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
2a1e0 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
2a1f0 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
2a200 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69  .** <ul>.**  <li
2a210 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
2a220 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20  text() followed 
2a230 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2a240 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
2a250 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
2a260 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c  olumn_blob() fol
2a270 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
2a280 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
2a290 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
2a2a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2a2b0 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  16() followed by
2a2c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a2d0 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a  bytes16()</li>.*
2a2e0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
2a2f0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f   other words, yo
2a300 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71  u should call sq
2a310 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2a320 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t(),.** sqlite3_
2a330 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f  column_blob(), o
2a340 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
2a350 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20  _text16() first 
2a360 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73  to force the res
2a370 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ult.** into the 
2a380 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20  desired format, 
2a390 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69  then invoke sqli
2a3a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2a3b0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
2a3c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2a3d0 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69  ) to find the si
2a3e0 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ze of the result
2a3f0 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61  .  Do not mix ca
2a400 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  lls.** to sqlite
2a410 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2a420 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2a430 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61  n_blob() with ca
2a440 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
2a450 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2a460 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d  (), and do not m
2a470 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ix calls to sqli
2a480 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2a490 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c  6().** with call
2a4a0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
2a4b0 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a  umn_bytes()..**.
2a4c0 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73  ** ^The pointers
2a4d0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61   returned are va
2a4e0 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65  lid until a type
2a4f0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
2a500 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62  rs as.** describ
2a510 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74  ed above, or unt
2a520 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  il [sqlite3_step
2a530 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2a540 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
2a550 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2a560 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  ()] is called.  
2a570 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63  ^The memory spac
2a580 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73  e used to hold s
2a590 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c  trings.** and BL
2a5a0 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74  OBs is freed aut
2a5b0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20  omatically.  Do 
2a5c0 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20  <b>not</b> pass 
2a5d0 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  the pointers ret
2a5e0 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  urned.** [sqlite
2a5f0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
2a600 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
2a610 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
2a620 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  into.** [sqlite3
2a630 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
2a640 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  ^(If a memory al
2a650 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
2a660 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65  ccurs during the
2a670 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61   evaluation of a
2a680 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72  ny.** of these r
2a690 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75  outines, a defau
2a6a0 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  lt value is retu
2a6b0 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75  rned.  The defau
2a6c0 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65  lt value.** is e
2a6d0 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65  ither the intege
2a6e0 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e  r 0, the floatin
2a6f0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30  g point number 0
2a700 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a  .0, or a NULL.**
2a710 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65   pointer.  Subse
2a720 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
2a730 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
2a740 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  )] will return.*
2a750 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
2a760 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  .)^.*/.const voi
2a770 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2a780 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  n_blob(sqlite3_s
2a790 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2a7a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2a7b0 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
2a7c0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2a7d0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2a7e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73  column_bytes16(s
2a7f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2a800 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20  t iCol);.double 
2a810 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2a820 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
2a830 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2a840 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2a850 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
2a860 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2a870 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
2a880 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
2a890 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
2a8a0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
2a8b0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
2a8c0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2a8d0 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  n_text(sqlite3_s
2a8e0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2a8f0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2a900 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2a910 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2a920 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
2a930 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a940 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
2a950 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
2a960 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
2a970 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2a980 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
2a990 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a  , int iCol);../*
2a9a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2a9b0 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64  stroy A Prepared
2a9c0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
2a9d0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2a9e0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
2a9f0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
2aa00 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b  ed to delete a [
2aa10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2aa20 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  nt]..** ^If the 
2aa30 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c  most recent eval
2aa40 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74  uation of the st
2aa50 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65  atement encounte
2aa60 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a  red no errors.**
2aa70 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65   or if the state
2aa80 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65  ment is never be
2aa90 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68  en evaluated, th
2aaa0 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  en sqlite3_final
2aab0 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  ize() returns.**
2aac0 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66   SQLITE_OK.  ^If
2aad0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2aae0 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73   evaluation of s
2aaf0 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65  tatement S faile
2ab00 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  d, then.** sqlit
2ab10 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
2ab20 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f  eturns the appro
2ab30 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
2ab40 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
2ab50 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e  ded error code].
2ab60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2ab70 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
2ab80 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63  routine can be c
2ab90 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69  alled at any poi
2aba0 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65  nt during.** the
2abb0 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b   life cycle of [
2abc0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2abd0 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65  nt] S:.** before
2abe0 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20   statement S is 
2abf0 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20  ever evaluated, 
2ac00 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20  after.** one or 
2ac10 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73  more calls to [s
2ac20 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
2ac30 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61   or after any ca
2ac40 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  ll.** to [sqlite
2ac50 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64  3_step()] regard
2ac60 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
2ac70 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65  or not the state
2ac80 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70  ment has.** comp
2ac90 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e  leted execution.
2aca0 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67  .**.** ^Invoking
2acb0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2acc0 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f  e() on a NULL po
2acd0 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c  inter is a harml
2ace0 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a  ess no-op..**.**
2acf0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
2ad00 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65   must finalize e
2ad10 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73  very [prepared s
2ad20 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64  tatement] in ord
2ad30 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72  er to avoid.** r
2ad40 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20  esource leaks.  
2ad50 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73  It is a grievous
2ad60 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61   error for the a
2ad70 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72  pplication to tr
2ad80 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72  y to use.** a pr
2ad90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ada0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
2adb0 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41  en finalized.  A
2adc0 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70  ny use of a prep
2add0 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
2ade0 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
2adf0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61  een finalized ca
2ae00 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  n result in unde
2ae10 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64  fined and.** und
2ae20 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f  esirable behavio
2ae30 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75  r such as segfau
2ae40 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72  lts and heap cor
2ae50 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20  ruption..*/.int 
2ae60 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2ae70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2ae80 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2ae90 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20  PI3REF: Reset A 
2aea0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2aeb0 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  nt Object.**.** 
2aec0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65  The sqlite3_rese
2aed0 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  t() function is 
2aee0 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20  called to reset 
2aef0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2af00 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
2af10 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
2af20 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
2af30 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
2af40 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c  ted..** ^Any SQL
2af50 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61   statement varia
2af60 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61  bles that had va
2af70 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68  lues bound to th
2af80 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  em using.** the 
2af90 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2afa0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
2afb0 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69  d_*() API] retai
2afc0 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a  n their values..
2afd0 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f  ** Use [sqlite3_
2afe0 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29  clear_bindings()
2aff0 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62  ] to reset the b
2b000 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e  indings..**.** ^
2b010 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2b020 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
2b030 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65   resets the [pre
2b040 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b050 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68   S.** back to th
2b060 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69  e beginning of i
2b070 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a  ts program..**.*
2b080 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2b090 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2b0a0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2b0b0 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
2b0c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2b0d0 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  S returned [SQLI
2b0e0 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49  TE_ROW] or [SQLI
2b0f0 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20  TE_DONE],.** or 
2b100 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  if [sqlite3_step
2b110 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62  (S)] has never b
2b120 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65  efore been calle
2b130 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20  d on S,.** then 
2b140 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2b150 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
2b160 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  TE_OK]..**.** ^I
2b170 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2b180 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2b190 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
2b1a0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2b1b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
2b1c0 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72  dicated an error
2b1d0 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74  , then.** [sqlit
2b1e0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
2b1f0 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
2b200 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
2b210 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
2b220 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2b230 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e  interface does n
2b240 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
2b250 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b  lues.** of any [
2b260 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2b270 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74  b|bindings] on t
2b280 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2b290 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e  tement] S..*/.in
2b2a0 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  t sqlite3_reset(
2b2b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2b2c0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2b2d0 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72  I3REF: Create Or
2b2e0 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75   Redefine SQL Fu
2b2f0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  nctions.** KEYWO
2b300 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63  RDS: {function c
2b310 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
2b320 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
2b330 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2b340 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2b350 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
2b360 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2b370 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2b380 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  s}.**.** ^These 
2b390 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
2b3a0 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
2b3b0 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
2b3c0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
2b3d0 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
2b3e0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
2b3f0 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
2b400 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
2b410 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
2b420 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
2b430 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
2b440 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
2b450 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77  differences betw
2b460 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75  een.** these rou
2b470 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65  tines are the te
2b480 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65  xt encoding expe
2b490 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  cted for.** the 
2b4a0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2b4b0 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   (the name of th
2b4c0 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67  e function being
2b4d0 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64   created).** and
2b4e0 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72   the presence or
2b4f0 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65   absence of a de
2b500 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
2b510 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70  k for.** the app
2b520 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
2b530 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
2b540 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2b550 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61  r is the [databa
2b560 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
2b570 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a  o which the SQL.
2b580 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ** function is t
2b590 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66  o be added.  ^If
2b5a0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
2b5b0 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
2b5c0 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ne database.** c
2b5d0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61  onnection then a
2b5e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2b5f0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2b600 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a   must be added.*
2b610 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  * to each databa
2b620 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65  se connection se
2b630 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  parately..**.** 
2b640 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
2b650 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
2b660 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
2b670 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
2b680 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69  ted or.** redefi
2b690 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74  ned.  ^The lengt
2b6a0 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
2b6b0 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
2b6c0 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38  bytes in a UTF-8
2b6d0 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69  .** representati
2b6e0 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  on, exclusive of
2b6f0 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
2b700 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61  ator.  ^Note tha
2b710 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65  t the name.** le
2b720 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
2b730 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f   UTF-8 bytes, no
2b740 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72  t characters nor
2b750 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20   UTF-16 bytes.  
2b760 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74  .** ^Any attempt
2b770 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
2b780 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
2b790 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
2b7a0 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49   result in [SQLI
2b7b0 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67  TE_MISUSE] being
2b7c0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2b7d0 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
2b7e0 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20  meter (nArg).** 
2b7f0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
2b800 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
2b810 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2b820 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
2b830 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73   takes. ^If this
2b840 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31   parameter is -1
2b850 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66  , then the SQL f
2b860 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
2b870 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65  gregate may take
2b880 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61   any number of a
2b890 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e  rguments between
2b8a0 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74   0 and the limit
2b8b0 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69  .** set by [sqli
2b8c0 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
2b8d0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
2b8e0 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65  N_ARG]).  If the
2b8f0 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
2b900 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ter is less than
2b910 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
2b920 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65  han 127 then the
2b930 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20   behavior is.** 
2b940 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2b950 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
2b960 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
2b970 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
2b980 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
2b990 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
2b9a0 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
2b9b0 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
2b9c0 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
2b9d0 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20 66 75  s.  Every SQL fu
2b9e0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2b9f0 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 61 62  ation must be ab
2ba00 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69  le to work.** wi
2ba10 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  th UTF-8, UTF-16
2ba20 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e  le, or UTF-16be.
2ba30 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65    But some imple
2ba40 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62  mentations may b
2ba50 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69  e.** more effici
2ba60 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63  ent with one enc
2ba70 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68  oding than anoth
2ba80 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61  er.  ^An applica
2ba90 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f  tion may.** invo
2baa0 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
2bab0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20  e_function() or 
2bac0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2bad0 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74  unction16() mult
2bae0 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69  iple.** times wi
2baf0 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  th the same func
2bb00 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69  tion but with di
2bb10 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f  fferent values o
2bb20 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e  f eTextRep..** ^
2bb30 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d  When multiple im
2bb40 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2bb50 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2bb60 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65  on are available
2bb70 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  , SQLite.** will
2bb80 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68   pick the one th
2bb90 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20  at involves the 
2bba0 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
2bbb0 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  data conversion.
2bbc0 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20  .** If there is 
2bbd0 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d  only a single im
2bbe0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69  plementation whi
2bbf0 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  ch does not care
2bc00 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e   what text.** en
2bc10 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20  coding is used, 
2bc20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
2bc30 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
2bc40 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e  be [SQLITE_ANY].
2bc50 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66  .**.** ^(The fif
2bc60 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
2bc70 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69  an arbitrary poi
2bc80 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65  nter.  The imple
2bc90 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
2bca0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  .** function can
2bcb0 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20   gain access to 
2bcc0 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69  this pointer usi
2bcd0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ng [sqlite3_user
2bce0 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a  _data()].)^.**.*
2bcf0 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65  * ^The sixth, se
2bd00 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68  venth and eighth
2bd10 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75   parameters, xFu
2bd20 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46  nc, xStep and xF
2bd30 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69  inal, are.** poi
2bd40 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75  nters to C-langu
2bd50 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  age functions th
2bd60 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
2bd70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2bd80 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e  .** aggregate. ^
2bd90 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  A scalar SQL fun
2bda0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
2bdb0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2bdc0 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a   of the xFunc.**
2bdd0 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20   callback only; 
2bde0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75  NULL pointers mu
2bdf0 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
2be00 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46  the xStep and xF
2be10 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65  inal.** paramete
2be20 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74  rs. ^An aggregat
2be30 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  e SQL function r
2be40 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
2be50 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74  mentation of xSt
2be60 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c  ep.** and xFinal
2be70 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   and NULL pointe
2be80 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  r must be passed
2be90 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20   for xFunc. ^To 
2bea0 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69  delete an existi
2beb0 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  ng.** SQL functi
2bec0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
2bed0 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74   pass NULL point
2bee0 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65  ers for all thre
2bef0 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61  e function.** ca
2bf00 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e  llbacks..**.** ^
2bf10 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61  (If the ninth pa
2bf20 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2bf30 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2bf40 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e  on_v2() is not N
2bf50 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  ULL,.** then it 
2bf60 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f  is destructor fo
2bf70 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
2bf80 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20  n data pointer. 
2bf90 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74  .** The destruct
2bfa0 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  or is invoked wh
2bfb0 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  en the function 
2bfc0 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68  is deleted, eith
2bfd0 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f  er by being.** o
2bfe0 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65  verloaded or whe
2bff0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
2c000 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
2c010 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74  .)^.** ^The dest
2c020 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69  ructor is also i
2c030 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61  nvoked if the ca
2c040 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
2c050 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2c060 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20  _v2() fails..** 
2c070 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75  ^When the destru
2c080 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66  ctor callback of
2c090 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d   the tenth param
2c0a0 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c  eter is invoked,
2c0b0 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64   it.** is passed
2c0c0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
2c0d0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f  nt which is a co
2c0e0 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  py of the applic
2c0f0 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70  ation data .** p
2c100 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73  ointer which was
2c110 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d   the fifth param
2c120 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2c130 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
2c140 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  v2()..**.** ^It 
2c150 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
2c160 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c  register multipl
2c170 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2c180 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a  s of the same.**
2c190 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20   functions with 
2c1a0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
2c1b0 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69  t with either di
2c1c0 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20  ffering numbers 
2c1d0 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  of.** arguments 
2c1e0 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65  or differing pre
2c1f0 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
2c200 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20  dings.  ^SQLite 
2c210 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20  will use.** the 
2c220 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74  implementation t
2c230 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79  hat most closely
2c240 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79   matches the way
2c250 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a   in which the.**
2c260 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
2c270 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74   used.  ^A funct
2c280 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
2c290 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65  on with a non-ne
2c2a0 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70  gative.** nArg p
2c2b0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65  arameter is a be
2c2c0 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  tter match than 
2c2d0 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  a function imple
2c2e0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a  mentation with.*
2c2f0 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72  * a negative nAr
2c300 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  g.  ^A function 
2c310 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72  where the prefer
2c320 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
2c330 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65  g.** matches the
2c340 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69   database encodi
2c350 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a  ng is a better.*
2c360 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  * match than a f
2c370 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
2c380 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69  e encoding is di
2c390 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41  fferent.  .** ^A
2c3a0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
2c3b0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
2c3c0 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65  ference is betwe
2c3d0 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55  en UTF16le and U
2c3e0 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63  TF16be.** is a c
2c3f0 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e  loser match than
2c400 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
2c410 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
2c420 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20  ifference is.** 
2c430 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64  between UTF8 and
2c440 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42   UTF16..**.** ^B
2c450 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e  uilt-in function
2c460 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61  s may be overloa
2c470 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69  ded by new appli
2c480 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2c490 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  unctions..**.** 
2c4a0 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ^An application-
2c4b0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2c4c0 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
2c4d0 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53   call other.** S
2c4e0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
2c4f0 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68  .  However, such
2c500 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a   calls must not.
2c510 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ** close the dat
2c520 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2c530 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72   nor finalize or
2c540 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
2c550 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
2c560 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75   in which the fu
2c570 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
2c580 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  g..*/.int sqlite
2c590 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2c5a0 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  n(.  sqlite3 *db
2c5b0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
2c5c0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
2c5d0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
2c5e0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
2c5f0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
2c600 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
2c610 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2c620 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2c630 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
2c640 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2c650 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2c660 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2c670 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
2c680 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
2c690 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2c6a0 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71  function16(.  sq
2c6b0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
2c6c0 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69  st void *zFuncti
2c6d0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
2c6e0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
2c6f0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
2c700 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
2c710 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2c720 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2c730 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2c740 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
2c750 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2c760 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2c770 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
2c780 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2c790 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
2c7a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2c7b0 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  n_v2(.  sqlite3 
2c7c0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
2c7d0 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
2c7e0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
2c7f0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
2c800 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
2c810 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
2c820 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2c830 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2c840 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
2c850 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
2c860 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2c870 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2c880 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
2c890 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20  e3_context*),.  
2c8a0 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
2c8b0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
2c8c0 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20   CAPI3REF: Text 
2c8d0 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20  Encodings.**.** 
2c8e0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64  These constant d
2c8f0 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f  efine integer co
2c900 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65  des that represe
2c910 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a  nt the various.*
2c920 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  * text encodings
2c930 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
2c940 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
2c950 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20   SQLITE_UTF8    
2c960 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
2c970 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20   SQLITE_UTF16LE 
2c980 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
2c990 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20   SQLITE_UTF16BE 
2c9a0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
2c9b0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20   SQLITE_UTF16   
2c9c0 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55         4    /* U
2c9d0 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  se native byte o
2c9e0 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rder */.#define 
2c9f0 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20  SQLITE_ANY      
2ca00 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71        5    /* sq
2ca10 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2ca20 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64  ction only */.#d
2ca30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
2ca40 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20  16_ALIGNED  8   
2ca50 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
2ca60 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c  te_collation onl
2ca70 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  y */../*.** CAPI
2ca80 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
2ca90 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45   Functions.** DE
2caa0 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
2cab0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
2cac0 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e  re [deprecated].
2cad0 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
2cae0 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
2caf0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
2cb00 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
2cb10 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  e, these functio
2cb20 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20  ns continue .** 
2cb30 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
2cb40 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61    However, new a
2cb50 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2cb60 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
2cb70 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
2cb80 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70  ctions.  To help
2cb90 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c   encourage peopl
2cba0 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73  e to avoid.** us
2cbb0 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69  ing these functi
2cbc0 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20  ons, we are not 
2cbd0 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f  going to tell yo
2cbe0 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a  u what they do..
2cbf0 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
2cc00 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45  E_OMIT_DEPRECATE
2cc10 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  D.SQLITE_DEPRECA
2cc20 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
2cc30 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28  aggregate_count(
2cc40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2cc50 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
2cc60 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
2cc70 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33  _expired(sqlite3
2cc80 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
2cc90 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
2cca0 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f  qlite3_transfer_
2ccb0 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
2ccc0 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f  _stmt*, sqlite3_
2ccd0 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
2cce0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
2ccf0 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63  lite3_global_rec
2cd00 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49  over(void);.SQLI
2cd10 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
2cd20 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  id sqlite3_threa
2cd30 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b  d_cleanup(void);
2cd40 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
2cd50 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  ED int sqlite3_m
2cd60 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64  emory_alarm(void
2cd70 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
2cd80 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69  3_int64,int),voi
2cd90 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
2cda0 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
2cdb0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
2cdc0 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f  ning SQL Functio
2cdd0 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75  n Parameter Valu
2cde0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  es.**.** The C-l
2cdf0 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
2ce00 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
2ce10 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
2ce20 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
2ce30 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
2ce40 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
2ce50 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
2ce60 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
2ce70 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
2ce80 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a  or aggregate..**
2ce90 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
2cea0 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
2ceb0 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
2cec0 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
2ced0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
2cee0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2cef0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
2cf00 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2cf10 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
2cf20 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
2cf30 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
2cf40 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2cf50 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
2cf60 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61  s..** The 3rd pa
2cf70 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
2cf80 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
2cf90 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
2cfa0 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63  rs to.** [protec
2cfb0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2cfc0 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
2cfd0 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
2cfe0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2cff0 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
2d000 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
2d010 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
2d020 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2d030 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
2d040 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
2d050 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2d060 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
2d070 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2d080 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20   work only with 
2d090 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2d0a0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2d0b0 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  s..** Any attemp
2d0c0 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72  t to use these r
2d0d0 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75  outines on an [u
2d0e0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2d0f0 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
2d100 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ect results in u
2d110 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
2d120 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  r..**.** ^These 
2d130 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
2d140 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
2d150 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d  esponding [colum
2d160 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
2d170 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ns].** except th
2d180 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e  at  these routin
2d190 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
2d1a0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2d1b0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2d1c0 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73  t.** pointer ins
2d1d0 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74  tead of a [sqlit
2d1e0 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65  e3_stmt*] pointe
2d1f0 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72  r and an integer
2d200 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a   column number..
2d210 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2d220 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2d230 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
2d240 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74  acts a UTF-16 st
2d250 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  ring.** in the n
2d260 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72  ative byte-order
2d270 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63   of the host mac
2d280 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  hine.  ^The.** s
2d290 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2d2a0 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69  t16be() and sqli
2d2b0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2d2c0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  le() interfaces.
2d2d0 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31  ** extract UTF-1
2d2e0 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
2d2f0 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
2d300 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
2d310 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tively..**.** ^(
2d320 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
2d330 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29  e_numeric_type()
2d340 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
2d350 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20  pts to apply.** 
2d360 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79  numeric affinity
2d370 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20   to the value.  
2d380 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
2d390 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a  an attempt is.**
2d3a0 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74   made to convert
2d3b0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e   the value to an
2d3c0 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61   integer or floa
2d3d0 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a  ting point.  If.
2d3e0 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72  ** such a conver
2d3f0 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65  sion is possible
2d400 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66   without loss of
2d410 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e   information (in
2d420 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c   other.** words,
2d430 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73   if the value is
2d440 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c   a string that l
2d450 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62  ooks like a numb
2d460 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  er).** then the 
2d470 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65  conversion is pe
2d480 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77  rformed.  Otherw
2d490 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f  ise no conversio
2d4a0 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65  n occurs..** The
2d4b0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
2d4c0 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74   | datatype] aft
2d4d0 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  er conversion is
2d4e0 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a   returned.)^.**.
2d4f0 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61  ** Please pay pa
2d500 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69  rticular attenti
2d510 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74  on to the fact t
2d520 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20  hat the pointer 
2d530 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d  returned.** from
2d540 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2d550 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
2d560 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
2d570 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2d580 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
2d590 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74  can be invalidat
2d5a0 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65  ed by a subseque
2d5b0 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
2d5c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2d5d0 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  es()], [sqlite3_
2d5e0 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d  value_bytes16()]
2d5f0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
2d600 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
2d610 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2d620 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ext16()]..**.** 
2d630 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
2d640 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
2d650 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
2d660 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c  ad as.** the SQL
2d670 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73   function that s
2d680 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c  upplied the [sql
2d690 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72  ite3_value*] par
2d6a0 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73  ameters..*/.cons
2d6b0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2d6c0 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
2d6d0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
2d6e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2d6f0 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
2d700 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
2d710 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73  _value_bytes16(s
2d720 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2d730 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76  double sqlite3_v
2d740 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69  alue_double(sqli
2d750 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2d760 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
2d770 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
2d780 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  *);.sqlite3_int6
2d790 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  4 sqlite3_value_
2d7a0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
2d7b0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  lue*);.const uns
2d7c0 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
2d7d0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73  te3_value_text(s
2d7e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2d7f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2d800 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2d810 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2d820 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2d830 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2d840 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
2d850 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
2d860 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
2d870 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
2d880 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
2d890 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
2d8a0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2d8b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
2d8c0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
2d8d0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2d8e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d8f0 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67  F: Obtain Aggreg
2d900 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  ate Function Con
2d910 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65  text.**.** Imple
2d920 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67  mentations of ag
2d930 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
2d940 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a  tions use this.*
2d950 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c  * routine to all
2d960 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72  ocate memory for
2d970 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73   storing their s
2d980 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tate..**.** ^The
2d990 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20   first time the 
2d9a0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2d9b0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
2d9c0 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
2d9d0 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69   .** for a parti
2d9e0 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20  cular aggregate 
2d9f0 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65  function, SQLite
2da00 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20  .** allocates N 
2da10 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65  of memory, zeroe
2da20 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72  s out that memor
2da30 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  y, and returns a
2da40 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
2da50 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e  he new memory. ^
2da60 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  On second and su
2da70 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
2da80 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67  o.** sqlite3_agg
2da90 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
2daa0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67   for the same ag
2dab0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
2dac0 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68   instance,.** th
2dad0 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73  e same buffer is
2dae0 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69   returned.  Sqli
2daf0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2db00 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61  ntext() is norma
2db10 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e  lly.** called on
2db20 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f  ce for each invo
2db30 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53  cation of the xS
2db40 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64  tep callback and
2db50 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73   then one.** las
2db60 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20  t time when the 
2db70 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20  xFinal callback 
2db80 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57  is invoked.  ^(W
2db90 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63  hen no rows matc
2dba0 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74  h.** an aggregat
2dbb0 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74  e query, the xSt
2dbc0 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66  ep() callback of
2dbd0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66   the aggregate f
2dbe0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65  unction.** imple
2dbf0 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76  mentation is nev
2dc00 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46  er called and xF
2dc10 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64  inal() is called
2dc20 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a   exactly once..*
2dc30 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73  * In those cases
2dc40 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  , sqlite3_aggreg
2dc50 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69  ate_context() mi
2dc60 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f  ght be called fo
2dc70 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  r the.** first t
2dc80 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  ime from within 
2dc90 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a  xFinal().)^.**.*
2dca0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61  * ^The sqlite3_a
2dcb0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2dcc0 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65  (C,N) routine re
2dcd0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
2dce0 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20  nter if N is.** 
2dcf0 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
2dd00 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66  al to zero or if
2dd10 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
2dd20 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  te error occurs.
2dd30 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f  .**.** ^(The amo
2dd40 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c  unt of space all
2dd50 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
2dd60 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2dd70 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64  ext(C,N) is.** d
2dd80 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65  etermined by the
2dd90 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20   N parameter on 
2dda0 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c  first successful
2ddb0 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67   call.  Changing
2ddc0 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
2ddd0 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74   N in subsequent
2dde0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
2ddf0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2de00 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74  xt() within.** t
2de10 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
2de20 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61  e function insta
2de30 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73  nce will not res
2de40 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a  ize the memory.*
2de50 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a  * allocation.)^.
2de60 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75  **.** ^SQLite au
2de70 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65  tomatically free
2de80 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
2de90 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71  ocated by .** sq
2dea0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2deb0 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74  context() when t
2dec0 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65  he aggregate que
2ded0 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a  ry concludes..**
2dee0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
2def0 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
2df00 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
2df10 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
2df20 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  t | SQL function
2df30 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69   context] that i
2df40 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
2df50 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
2df60 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20  xStep or xFinal 
2df70 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  callback routine
2df80 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
2df90 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a   the aggregate.*
2dfa0 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  * function..**.*
2dfb0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
2dfc0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
2dfd0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
2dfe0 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
2dff0 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  he aggregate SQL
2e000 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
2e010 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
2e020 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2e030 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33  _context(sqlite3
2e040 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
2e050 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Bytes);../*.** C
2e060 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61  API3REF: User Da
2e070 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  ta For Functions
2e080 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2e090 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20  te3_user_data() 
2e0a0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2e0b0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
2e0c0 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  he pointer that 
2e0d0 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74  was the pUserDat
2e0e0 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65  a parameter (the
2e0f0 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a   5th parameter).
2e100 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
2e110 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2e120 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
2e130 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2e140 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
2e150 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
2e160 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
2e170 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
2e180 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
2e190 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
2e1a0 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
2e1b0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
2e1c0 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
2e1d0 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  ich.** the appli
2e1e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2e1f0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
2e200 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
2e210 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73  ite3_user_data(s
2e220 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2e230 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e240 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
2e250 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74  ection For Funct
2e260 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ions.**.** ^The 
2e270 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
2e280 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65  db_handle() inte
2e290 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2e2a0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
2e2b0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64  ointer to the [d
2e2c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2e2d0 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72  on] (the 1st par
2e2e0 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
2e2f0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2e300 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
2e310 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
2e320 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2e330 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
2e340 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
2e350 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
2e360 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
2e370 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73  d function..*/.s
2e380 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
2e390 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
2e3a0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
2e3b0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2e3c0 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41  3REF: Function A
2e3d0 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a  uxiliary Data.**
2e3e0 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** The followin
2e3f0 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20  g two functions 
2e400 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73  may be used by s
2e410 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
2e420 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69  ons to.** associ
2e430 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74  ate metadata wit
2e440 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65  h argument value
2e450 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76  s. If the same v
2e460 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74  alue is passed t
2e470 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e  o.** multiple in
2e480 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
2e490 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
2e4a0 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20  on during query 
2e4b0 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72  execution, under
2e4c0 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73  .** some circums
2e4d0 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63  tances the assoc
2e4e0 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d  iated metadata m
2e4f0 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e  ay be preserved.
2e500 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20   This may.** be 
2e510 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c  used, for exampl
2e520 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75  e, to add a regu
2e530 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d  lar-expression m
2e540 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a  atching scalar.*
2e550 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  * function. The 
2e560 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e  compiled version
2e570 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20   of the regular 
2e580 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74  expression is st
2e590 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64  ored as.** metad
2e5a0 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77  ata associated w
2e5b0 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75  ith the SQL valu
2e5c0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
2e5d0 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
2e5e0 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20  on.** pattern.  
2e5f0 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67  The compiled reg
2e600 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
2e610 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e  can be reused on
2e620 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76   multiple.** inv
2e630 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
2e640 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f  same function so
2e650 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e   that the origin
2e660 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  al pattern strin
2e670 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65  g.** does not ne
2e680 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69  ed to be recompi
2e690 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f  led on each invo
2e6a0 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  cation..**.** ^T
2e6b0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
2e6c0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
2e6d0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2e6e0 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61  nter to the meta
2e6f0 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74  data.** associat
2e700 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
2e710 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
2e720 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68  function with th
2e730 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  e Nth argument.*
2e740 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61  * value to the a
2e750 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2e760 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66  ed function. ^If
2e770 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73   no metadata has
2e780 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65   been ever.** be
2e790 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e  en set for the N
2e7a0 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  th argument of t
2e7b0 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20  he function, or 
2e7c0 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  if the correspon
2e7d0 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ding.** function
2e7e0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63   parameter has c
2e7f0 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65  hanged since the
2e800 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73   meta-data was s
2e810 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69  et,.** then sqli
2e820 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
2e830 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
2e840 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
2e850 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74  ^The sqlite3_set
2e860 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
2e870 66 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d  face saves the m
2e880 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74  etadata.** point
2e890 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64  ed to by its 3rd
2e8a0 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
2e8b0 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74  e metadata for t
2e8c0 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d  he N-th.** argum
2e8d0 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ent of the appli
2e8e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2e8f0 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71  unction.  Subseq
2e900 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  uent.** calls to
2e910 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
2e920 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74  data() might ret
2e930 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69  urn this data, i
2e940 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20  f it has.** not 
2e950 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a  been destroyed..
2e960 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74  ** ^If it is not
2e970 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69   NULL, SQLite wi
2e980 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65  ll invoke the de
2e990 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63  structor.** func
2e9a0 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68  tion given by th
2e9b0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
2e9c0 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
2e9d0 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74  uxdata() on.** t
2e9e0 68 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e  he metadata when
2e9f0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
2ea00 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ng function para
2ea10 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a  meter changes.**
2ea20 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c   or when the SQL
2ea30 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c   statement compl
2ea40 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20  etes, whichever 
2ea50 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a  comes first..**.
2ea60 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65  ** SQLite is fre
2ea70 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65  e to call the de
2ea80 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f  structor and dro
2ea90 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e  p metadata on an
2eaa0 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f  y.** parameter o
2eab0 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61  f any function a
2eac0 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68  t any time.  ^Th
2ead0 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65  e only guarantee
2eae0 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20   is that.** the 
2eaf0 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20  destructor will 
2eb00 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65  be called before
2eb10 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73   the metadata is
2eb20 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20   dropped..**.** 
2eb30 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d  ^(In practice, m
2eb40 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65  etadata is prese
2eb50 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e  rved between fun
2eb60 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a  ction calls for.
2eb70 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74  ** expressions t
2eb80 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74  hat are constant
2eb90 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
2eba0 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20  . This includes 
2ebb0 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65  literal.** value
2ebc0 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72  s and [parameter
2ebd0 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  s].)^.**.** Thes
2ebe0 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
2ebf0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
2ec00 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
2ec10 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53  n which.** the S
2ec20 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
2ec30 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
2ec40 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  *sqlite3_get_aux
2ec50 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
2ec60 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76  text*, int N);.v
2ec70 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
2ec80 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
2ec90 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c  context*, int N,
2eca0 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29   void*, void (*)
2ecb0 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a  (void*));.../*.*
2ecc0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73  * CAPI3REF: Cons
2ecd0 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53  tants Defining S
2ece0 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f  pecial Destructo
2ecf0 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a  r Behavior.**.**
2ed00 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69   These are speci
2ed10 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68  al values for th
2ed20 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61  e destructor tha
2ed30 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61  t is passed in a
2ed40 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61  s the.** final a
2ed50 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69  rgument to routi
2ed60 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
2ed70 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d  3_result_blob()]
2ed80 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72  .  ^If the destr
2ed90 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  uctor.** argumen
2eda0 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54  t is SQLITE_STAT
2edb0 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  IC, it means tha
2edc0 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f  t the content po
2edd0 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e  inter is constan
2ede0 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65  t.** and will ne
2edf0 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20  ver change.  It 
2ee00 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
2ee10 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20   be destroyed.  
2ee20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  ^The.** SQLITE_T
2ee30 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d  RANSIENT value m
2ee40 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
2ee50 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c  ntent will likel
2ee60 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74  y change in.** t
2ee70 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61  he near future a
2ee80 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73  nd that SQLite s
2ee90 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f  hould make its o
2eea0 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
2eeb0 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  of.** the conten
2eec0 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  t before returni
2eed0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79  ng..**.** The ty
2eee0 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61  pedef is necessa
2eef0 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  ry to work aroun
2ef00 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65  d problems in ce
2ef10 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d  rtain.** C++ com
2ef20 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63  pilers.  See tic
2ef30 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79  ket #2191..*/.ty
2ef40 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
2ef50 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
2ef60 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64  type)(void*);.#d
2ef70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41  efine SQLITE_STA
2ef80 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74  TIC      ((sqlit
2ef90 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
2efa0 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51  pe)0).#define SQ
2efb0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20  LITE_TRANSIENT  
2efc0 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
2efd0 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a  uctor_type)-1)..
2efe0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2eff0 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75  Setting The Resu
2f000 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e  lt Of An SQL Fun
2f010 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ction.**.** Thes
2f020 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
2f030 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63  sed by the xFunc
2f040 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62   or xFinal callb
2f050 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70  acks that.** imp
2f060 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74  lement SQL funct
2f070 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
2f080 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71  tes.  See.** [sq
2f090 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2f0a0 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
2f0b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2f0c0 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f  ction16()].** fo
2f0d0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
2f0e0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
2f0f0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2f100 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c  work very much l
2f110 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74  ike the [paramet
2f120 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69  er binding] fami
2f130 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f  ly of.** functio
2f140 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20  ns used to bind 
2f150 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70  values to host p
2f160 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65  arameters in pre
2f170 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2f180 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68  ..** Refer to th
2f190 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  e [SQL parameter
2f1a0 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
2f1b0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
2f1c0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
2f1d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2f1e0 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74  esult_blob() int
2f1f0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
2f200 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
2f210 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
2f220 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2f230 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68  o be the BLOB wh
2f240 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70  ose content is p
2f250 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20  ointed.** to by 
2f260 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
2f270 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69  eter and which i
2f280 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77  s N bytes long w
2f290 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
2f2a0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2f2b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2f2c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
2f2d0 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
2f2e0 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74  s set the result
2f2f0 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
2f300 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2f310 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
2f320 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20  BLOB containing 
2f330 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65  all zero.** byte
2f340 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e  s and N bytes in
2f350 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69   size, where N i
2f360 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
2f370 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
2f380 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2f390 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
2f3a0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  le() interface s
2f3b0 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
2f3c0 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
2f3d0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2f3e0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66  nction to be a f
2f3f0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
2f400 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  lue specified.**
2f410 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75   by its 2nd argu
2f420 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
2f430 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f440 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
2f450 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2f460 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  16() functions.*
2f470 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c  * cause the impl
2f480 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63  emented SQL func
2f490 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e  tion to throw an
2f4a0 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e   exception..** ^
2f4b0 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
2f4c0 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74  string pointed t
2f4d0 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20  o by the.** 2nd 
2f4e0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c  parameter of sql
2f4f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2f500 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  r() or sqlite3_r
2f510 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
2f520 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f  ** as the text o
2f530 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  f an error messa
2f540 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74  ge.  ^SQLite int
2f550 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f  erprets the erro
2f560 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72  r.** message str
2f570 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
2f580 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
2f590 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74  as UTF-8. ^SQLit
2f5a0 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20  e.** interprets 
2f5b0 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  the string from 
2f5c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2f5d0 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d  rror16() as UTF-
2f5e0 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20  16 in native.** 
2f5f0 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66  byte order.  ^If
2f600 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
2f610 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2f620 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
2f630 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
2f640 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
2f650 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53   negative then S
2f660 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74  QLite takes as t
2f670 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
2f680 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20  age all text up 
2f690 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
2f6a0 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
2f6b0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69  ..** ^If the thi
2f6c0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2f6d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2f6e0 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  rror() or.** sql
2f6f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2f700 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67  r16() is non-neg
2f710 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
2f720 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e  e takes that man
2f730 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20  y.** bytes (not 
2f740 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d  characters) from
2f750 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2f760 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20  er as the error 
2f770 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65  message..** ^The
2f780 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f790 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
2f7a0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2f7b0 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  16().** routines
2f7c0 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20   make a private 
2f7d0 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f  copy of the erro
2f7e0 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62  r message text b
2f7f0 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65  efore.** they re
2f800 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68  turn.  Hence, th
2f810 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
2f820 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74  on can deallocat
2f830 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74  e or.** modify t
2f840 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68  he text after th
2f850 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75  ey return withou
2f860 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20  t harm..** ^The 
2f870 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2f880 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63  rror_code() func
2f890 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65  tion changes the
2f8a0 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72   error code.** r
2f8b0 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74  eturned by SQLit
2f8c0 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66  e as a result of
2f8d0 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66   an error in a f
2f8e0 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65  unction.  ^By de
2f8f0 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72  fault,.** the er
2f900 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49  ror code is SQLI
2f910 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75  TE_ERROR.  ^A su
2f920 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
2f930 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f940 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
2f950 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2f960 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68  or16() resets th
2f970 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20  e error code to 
2f980 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a  SQLITE_ERROR..**
2f990 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2f9a0 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29  _result_toobig()
2f9b0 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
2f9c0 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
2f9d0 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e  w an error.** in
2f9e0 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
2f9f0 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69  string or BLOB i
2fa00 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65  s too long to re
2fa10 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  present..**.** ^
2fa20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2fa30 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72  lt_nomem() inter
2fa40 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
2fa50 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  te to throw an e
2fa60 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69  rror.** indicati
2fa70 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79  ng that a memory
2fa80 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
2fa90 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2faa0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
2fab0 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  t() interface se
2fac0 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
2fad0 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
2fae0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2faf0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2fb00 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e   the 32-bit sign
2fb10 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
2fb20 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
2fb30 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
2fb40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2fb50 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e  esult_int64() in
2fb60 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
2fb70 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
2fb80 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
2fb90 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2fba0 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36  tion to be the 6
2fbb0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
2fbc0 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
2fbd0 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
2fbe0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
2fbf0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2fc00 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66  lt_null() interf
2fc10 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
2fc20 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
2fc30 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2fc40 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2fc50 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a   to be NULL..**.
2fc60 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2fc70 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73  result_text(), s
2fc80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2fc90 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  xt16(),.** sqlit
2fca0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2fcb0 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  le(), and sqlite
2fcc0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
2fcd0 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
2fce0 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e  * set the return
2fcf0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70   value of the ap
2fd00 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2fd10 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2fd20 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e  .** a text strin
2fd30 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65  g which is repre
2fd40 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c  sented as UTF-8,
2fd50 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
2fd60 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54  yte order,.** UT
2fd70 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69  F-16 little endi
2fd80 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
2fd90 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g endian, respec
2fda0 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69  tively..** ^SQLi
2fdb0 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78  te takes the tex
2fdc0 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68  t result from th
2fdd0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72  e application fr
2fde0 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61  om.** the 2nd pa
2fdf0 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73  rameter of the s
2fe00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2fe10 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  xt* interfaces..
2fe20 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
2fe30 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2fe40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2fe50 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
2fe60 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
2fe70 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
2fe80 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72  s result text fr
2fe90 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
2fea0 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20  eter.** through 
2feb0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
2fec0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
2fed0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
2fee0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
2fef0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2ff00 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
2ff10 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
2ff20 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73  en as many bytes
2ff30 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
2ff40 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a  ) of the text.**
2ff50 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
2ff60 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
2ff70 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68   are taken as th
2ff80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2ff90 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f  fined.** functio
2ffa0 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68  n result.  If th
2ffb0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
2ffc0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
2ffd0 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74   then it.** must
2ffe0 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66   be the byte off
2fff0 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72  set into the str
30000 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e 55  ing where the NU
30010 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75  L terminator wou
30020 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20  ld.** appear if 
30030 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65  the string where
30040 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e   NUL terminated.
30050 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61    If any NUL cha
30060 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a  racters occur.**
30070 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61   in the string a
30080 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 20  t a byte offset 
30090 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 61  that is less tha
300a0 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  n the value of t
300b0 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65  he 3rd.** parame
300c0 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ter, then the re
300d0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77  sulting string w
300e0 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65  ill contain embe
300f0 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68  dded NULs and th
30100 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65  e.** result of e
30110 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61  xpressions opera
30120 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20  ting on strings 
30130 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55  with embedded NU
30140 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  Ls is undefined.
30150 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
30160 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
30170 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30180 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
30190 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
301a0 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20  esult_blob is a 
301b0 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
301c0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61  , then SQLite ca
301d0 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63  lls that.** func
301e0 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74  tion as the dest
301f0 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65  ructor on the te
30200 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
30210 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a  t when it has.**
30220 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
30230 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
30240 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
30250 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
30260 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
30270 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20  * interfaces or 
30280 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  to.** sqlite3_re
30290 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
302a0 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
302b0 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  t SQLITE_STATIC,
302c0 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20   then SQLite.** 
302d0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
302e0 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
302f0 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74  sult is in const
30300 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ant space and do
30310 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74  es not.** copy t
30320 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
30330 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20  e parameter nor 
30340 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f  call a destructo
30350 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74  r on the content
30360 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20  .** when it has 
30370 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
30380 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
30390 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
303a0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
303b0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
303c0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
303d0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
303e0 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
303f0 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
30400 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a  LITE_TRANSIENT.*
30410 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61  * then SQLite ma
30420 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
30430 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70  e result into sp
30440 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ace obtained fro
30450 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  m.** from [sqlit
30460 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66  e3_malloc()] bef
30470 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a  ore it returns..
30480 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
30490 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
304a0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
304b0 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
304c0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
304d0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
304e0 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20  on to be a copy 
304f0 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63  the.** [unprotec
30500 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
30510 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  e] object specif
30520 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70  ied by the 2nd p
30530 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a  arameter.  ^The.
30540 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
30550 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
30560 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ace makes a copy
30570 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
30580 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68  _value].** so th
30590 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
305a0 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64  value] specified
305b0 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
305c0 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a  r may change or.
305d0 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ** be deallocate
305e0 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
305f0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72  result_value() r
30600 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68  eturns without h
30610 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74  arm..** ^A [prot
30620 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
30630 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20  lue] object may 
30640 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77  always be used w
30650 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  here an.** [unpr
30660 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
30670 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73  value] object is
30680 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69   required, so ei
30690 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20  ther.** kind of 
306a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
306b0 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73  object can be us
306c0 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74  ed with this int
306d0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66  erface..**.** If
306e0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
306f0 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
30700 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65  within the diffe
30710 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74  rent thread.** t
30720 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74  han the one cont
30730 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69  aining the appli
30740 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
30750 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63  unction that rec
30760 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71  eived.** the [sq
30770 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70  lite3_context] p
30780 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75  ointer, the resu
30790 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
307a0 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
307b0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73  e3_result_blob(s
307c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
307d0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
307e0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
307f0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
30800 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73  _result_double(s
30810 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
30820 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73   double);.void s
30830 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
30840 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ror(sqlite3_cont
30850 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
30860 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
30870 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
30880 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  or16(sqlite3_con
30890 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
308a0 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  d*, int);.void s
308b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
308c0 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74  ror_toobig(sqlit
308d0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
308e0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
308f0 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71  t_error_nomem(sq
30900 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
30910 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
30920 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
30930 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
30940 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
30950 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
30960 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
30970 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
30980 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36  ite3_result_int6
30990 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  4(sqlite3_contex
309a0 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t*, sqlite3_int6
309b0 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  4);.void sqlite3
309c0 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c  _result_null(sql
309d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
309e0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
309f0 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ult_text(sqlite3
30a00 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
30a10 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69   char*, int, voi
30a20 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
30a30 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
30a40 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  t_text16(sqlite3
30a50 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
30a60 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
30a70 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
30a80 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
30a90 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  t_text16le(sqlit
30aa0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
30ab0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
30ac0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
30ad0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
30ae0 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  lt_text16be(sqli
30af0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
30b00 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
30b10 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
30b20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
30b30 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ult_value(sqlite
30b40 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
30b50 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69  te3_value*);.voi
30b60 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
30b70 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
30b80 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
30b90 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
30ba0 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20  REF: Define New 
30bb0 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e  Collating Sequen
30bc0 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ces.**.** ^These
30bd0 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20   functions add, 
30be0 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66  remove, or modif
30bf0 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20  y a [collation] 
30c00 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
30c10 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
30c20 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
30c30 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69  cified as the fi
30c40 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
30c50 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
30c60 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69   the collation i
30c70 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
30c80 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  .** for sqlite3_
30c90 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
30ca0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
30cb0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
30cc0 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54  v2().** and a UT
30cd0 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
30ce0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
30cf0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
30d00 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
30d10 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e  )..** ^Collation
30d20 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70   names that comp
30d30 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64  are equal accord
30d40 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ing to [sqlite3_
30d50 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a  strnicmp()] are.
30d60 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  ** considered to
30d70 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d   be the same nam
30d80 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74  e..**.** ^(The t
30d90 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65  hird argument (e
30da0 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65  TextRep) must be
30db0 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73   one of the cons
30dc0 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  tants:.** <ul>.*
30dd0 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
30de0 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  TF8],.** <li> [S
30df0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a  QLITE_UTF16LE],.
30e00 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
30e10 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69  UTF16BE],.** <li
30e20 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  > [SQLITE_UTF16]
30e30 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
30e40 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
30e50 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  ED]..** </ul>)^.
30e60 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70  ** ^The eTextRep
30e70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d   argument determ
30e80 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e  ines the encodin
30e90 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73  g of strings pas
30ea0 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f  sed.** to the co
30eb0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
30ec0 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c   callback, xCall
30ed0 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  back..** ^The [S
30ee0 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64  QLITE_UTF16] and
30ef0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
30f00 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66  LIGNED] values f
30f10 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66  or eTextRep.** f
30f20 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20  orce strings to 
30f30 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61  be UTF16 with na
30f40 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
30f50 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
30f60 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
30f70 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52  value for eTextR
30f80 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67  ep forces string
30f90 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e  s to begin.** on
30fa0 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64   an even byte ad
30fb0 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dress..**.** ^Th
30fc0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
30fd0 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61  t, pArg, is an a
30fe0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
30ff0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
31000 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67  passed.** throug
31010 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  h as the first a
31020 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
31030 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
31040 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  n callback..**.*
31050 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
31060 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b  ument, xCallback
31070 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  , is a pointer t
31080 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
31090 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75  function..** ^Mu
310a0 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67  ltiple collating
310b0 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62   functions can b
310c0 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  e registered usi
310d0 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  ng the same name
310e0 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66   but.** with dif
310f0 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20  ferent eTextRep 
31100 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53  parameters and S
31110 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77  QLite will use w
31120 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63  hichever.** func
31130 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68  tion requires th
31140 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
31150 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d  f data transform
31160 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68  ation..** ^If th
31170 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75  e xCallback argu
31180 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65  ment is NULL the
31190 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  n the collating 
311a0 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64  function is.** d
311b0 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61  eleted.  ^When a
311c0 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ll collating fun
311d0 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68  ctions having th
311e0 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20  e same name are 
311f0 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74  deleted,.** that
31200 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   collation is no
31210 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a   longer usable..
31220 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61  **.** ^The colla
31230 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
31240 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
31250 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66  d with a copy of
31260 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70   the pArg .** ap
31270 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
31280 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20  ointer and with 
31290 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74  two strings in t
312a0 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
312b0 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
312c0 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e  eTextRep argumen
312d0 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e  t.  The collatin
312e0 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
312f0 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74  return an.** int
31300 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67  eger that is neg
31310 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20  ative, zero, or 
31320 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74  positive.** if t
31330 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20  he first string 
31340 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71  is less than, eq
31350 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74  ual to, or great
31360 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f  er than the seco
31370 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  nd,.** respectiv
31380 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e  ely.  A collatin
31390 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
313a0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68  always return th
313b0 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a  e same answer.**
313c0 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20   given the same 
313d0 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20  inputs.  If two 
313e0 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e  or more collatin
313f0 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  g functions are 
31400 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f  registered.** to
31410 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74   the same collat
31420 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20  ion name (using 
31430 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52  different eTextR
31440 65 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20  ep values) then 
31450 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65  all.** must give
31460 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61   an equivalent a
31470 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b  nswer when invok
31480 65 64 20 77 69 74 68 20 65 71 75 69 76 61 6c 65  ed with equivale
31490 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  nt strings..** T
314a0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
314b0 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20  ction must obey 
314c0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72  the following pr
314d0 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c  operties for all
314e0 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42  .** strings A, B
314f0 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c  , and C:.**.** <
31500 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  ol>.** <li> If A
31510 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a  ==B then B==A..*
31520 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61  * <li> If A==B a
31530 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d  nd B==C then A==
31540 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26  C..** <li> If A&
31550 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41  lt;B THEN B&gt;A
31560 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c  ..** <li> If A&l
31570 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74  t;B and B&lt;C t
31580 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c  hen A&lt;C..** <
31590 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  /ol>.**.** If a 
315a0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
315b0 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20  on fails any of 
315c0 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72  the above constr
315d0 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a  aints and that.*
315e0 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  * collating func
315f0 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65  tion is  registe
31600 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68  red and used, th
31610 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
31620 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20  of SQLite.** is 
31630 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
31640 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72   ^The sqlite3_cr
31650 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
31660 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  2() works like s
31670 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
31680 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74  llation().** wit
31690 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74  h the addition t
316a0 68 61 74 20 74 68 65 20 78 44 65 73 74 72 6f 79  hat the xDestroy
316b0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
316c0 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65  oked on pArg whe
316d0 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69  n.** the collati
316e0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  ng function is d
316f0 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c  eleted..** ^Coll
31700 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
31710 61 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e  are deleted when
31720 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69   they are overri
31730 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a  dden by later.**
31740 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f   calls to the co
31750 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  llation creation
31760 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68   functions or wh
31770 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  en the.** [datab
31780 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
31790 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20  is closed using 
317a0 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
317b0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44  ]..**.** ^The xD
317c0 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20  estroy callback 
317d0 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61  is <u>not</u> ca
317e0 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20  lled if the .** 
317f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
31800 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75  ollation_v2() fu
31810 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41  nction fails.  A
31820 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
31830 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
31840 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
31850 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20  ion_v2() with a 
31860 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f  non-NULL xDestro
31870 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  y argument shoul
31880 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20  d .** check the 
31890 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20  return code and 
318a0 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61  dispose of the a
318b0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
318c0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73  pointer.** thems
318d0 65 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 61  elves rather tha
318e0 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69  n expecting SQLi
318f0 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20  te to deal with 
31900 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20  it for them..** 
31910 54 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e  This is differen
31920 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68  t from every oth
31930 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
31940 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73  ace.  The incons
31950 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75  istency .** is u
31960 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63  nfortunate but c
31970 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
31980 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
31990 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20  g backwards .** 
319a0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
319b0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20  *.** See also:  
319c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
319d0 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64  on_needed()] and
319e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
319f0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e  ion_needed16()].
31a00 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
31a10 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
31a20 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
31a30 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
31a40 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
31a50 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
31a60 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
31a70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
31a80 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
31a90 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69  onst void*).);.i
31aa0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
31ab0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a  e_collation_v2(.
31ac0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
31ad0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
31ae0 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
31af0 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67  p, .  void *pArg
31b00 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
31b10 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
31b20 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
31b30 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69  st void*),.  voi
31b40 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
31b50 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  d*).);.int sqlit
31b60 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
31b70 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
31b80 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  *, .  const void
31b90 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65   *zName,.  int e
31ba0 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
31bb0 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
31bc0 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
31bd0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
31be0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
31bf0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
31c00 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65  EF: Collation Ne
31c10 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  eded Callbacks.*
31c20 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68  *.** ^To avoid h
31c30 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65  aving to registe
31c40 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20  r all collation 
31c50 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65  sequences before
31c60 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63   a database.** c
31c70 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69  an be used, a si
31c80 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ngle callback fu
31c90 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
31ca0 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68  gistered with th
31cb0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
31cc0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65  onnection] to be
31cd0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
31ce0 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63  r an undefined c
31cf0 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
31d00 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64  ence is required
31d10 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
31d20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69  function is regi
31d30 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
31d40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
31d50 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c  on_needed() API,
31d60 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70  .** then it is p
31d70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20  assed the names 
31d80 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  of undefined col
31d90 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
31da0 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65   as strings.** e
31db0 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e  ncoded in UTF-8.
31dc0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c   ^If sqlite3_col
31dd0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
31de0 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68  ) is used,.** th
31df0 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73  e names are pass
31e00 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
31e10 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62  machine native b
31e20 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41  yte order..** ^A
31e30 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20   call to either 
31e40 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65  function replace
31e50 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63  s the existing c
31e60 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20  ollation-needed 
31e70 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
31e80 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  ^(When the callb
31e90 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ack is invoked, 
31ea0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
31eb0 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63  nt passed is a c
31ec0 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65  opy.** of the se
31ed0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
31ee0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
31ef0 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a  on_needed() or.*
31f00 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  * sqlite3_collat
31f10 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20  ion_needed16(). 
31f20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
31f30 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61  ment is the data
31f40 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
31f50 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  on.  The third a
31f60 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
31f70 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  f [SQLITE_UTF8],
31f80 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
31f90 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  ],.** or [SQLITE
31fa0 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63  _UTF16LE], indic
31fb0 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64  ating the most d
31fc0 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66  esirable form of
31fd0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a   the collation.*
31fe0 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74  * sequence funct
31ff0 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54  ion required.  T
32000 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
32010 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
32020 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72  of the.** requir
32030 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
32040 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  uence.)^.**.** T
32050 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
32060 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69  tion should regi
32070 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64  ster the desired
32080 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67   collation using
32090 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
320a0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d  ate_collation()]
320b0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
320c0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d  e_collation16()]
320d0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
320e0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
320f0 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  n_v2()]..*/.int 
32100 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
32110 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69  n_needed(.  sqli
32120 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20  te3*, .  void*, 
32130 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
32140 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
32150 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61  extRep,const cha
32160 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  r*).);.int sqlit
32170 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
32180 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ded16(.  sqlite3
32190 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76  *, .  void*,.  v
321a0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
321b0 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
321c0 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  ep,const void*).
321d0 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54  );..#ifdef SQLIT
321e0 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a  E_HAS_CODEC./*.*
321f0 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65  * Specify the ke
32200 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74  y for an encrypt
32210 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68  ed database.  Th
32220 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  is routine shoul
32230 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72  d be.** called r
32240 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74  ight after sqlit
32250 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a  e3_open()..**.**
32260 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
32270 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
32280 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
32290 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
322a0 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
322b0 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
322c0 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74  te3_key(.  sqlit
322d0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
322e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
322f0 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
32300 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
32310 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
32320 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b  Key     /* The k
32330 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
32340 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f  Change the key o
32350 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  n an open databa
32360 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72  se.  If the curr
32370 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20  ent database is 
32380 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64  not.** encrypted
32390 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  , this routine w
323a0 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20  ill encrypt it. 
323b0 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e   If pNew==0 or n
323c0 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64  New==0, the.** d
323d0 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79  atabase is decry
323e0 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  pted..**.** The 
323f0 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
32400 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
32410 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
32420 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
32430 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
32440 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
32450 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20  ekey(.  sqlite3 
32460 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
32470 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
32480 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
32490 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
324a0 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
324b0 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20       /* The new 
324c0 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
324d0 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74   Specify the act
324e0 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20  ivation key for 
324f0 61 20 53 45 45 20 64 61 74 61 62 61 73 65 2e 20  a SEE database. 
32500 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69   Unless .** acti
32510 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74  vated, none of t
32520 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20  he SEE routines 
32530 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f  will work..*/.vo
32540 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76  id sqlite3_activ
32550 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74  ate_see(.  const
32560 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61   char *zPassPhra
32570 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74  se        /* Act
32580 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a  ivation phrase *
32590 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66  /.);.#endif..#if
325a0 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c  def SQLITE_ENABL
325b0 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70  E_CEROD./*.** Sp
325c0 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61  ecify the activa
325d0 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43  tion key for a C
325e0 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20  EROD database.  
325f0 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76  Unless .** activ
32600 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68  ated, none of th
32610 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73  e CEROD routines
32620 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76   will work..*/.v
32630 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69  oid sqlite3_acti
32640 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f  vate_cerod(.  co
32650 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50  nst char *zPassP
32660 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20  hrase        /* 
32670 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73  Activation phras
32680 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a  e */.);.#endif..
32690 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
326a0 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f  Suspend Executio
326b0 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69  n For A Short Ti
326c0 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  me.**.** The sql
326d0 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e  ite3_sleep() fun
326e0 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65  ction causes the
326f0 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20   current thread 
32700 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75  to suspend execu
32710 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c  tion.** for at l
32720 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66  east a number of
32730 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70   milliseconds sp
32740 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70  ecified in its p
32750 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
32760 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  If the operating
32770 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74   system does not
32780 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72   support sleep r
32790 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20  equests with.** 
327a0 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65  millisecond time
327b0 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65   resolution, the
327c0 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20  n the time will 
327d0 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f  be rounded up to
327e0 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20  .** the nearest 
327f0 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62  second. The numb
32800 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
32810 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75  ds of sleep actu
32820 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65  ally.** requeste
32830 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61  d from the opera
32840 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72  ting system is r
32850 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
32860 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74  SQLite implement
32870 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  s this interface
32880 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20   by calling the 
32890 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68  xSleep().** meth
328a0 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
328b0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
328c0 6f 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20  object.  If the 
328d0 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a  xSleep() method.
328e0 2a 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  ** of the defaul
328f0 74 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70  t VFS is not imp
32900 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74  lemented correct
32910 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65  ly, or not imple
32920 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c  mented at.** all
32930 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
32940 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ior of sqlite3_s
32950 6c 65 65 70 28 29 20 6d 61 79 20 64 65 76 69 61  leep() may devia
32960 74 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63  te from the desc
32970 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68  ription.** in th
32980 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67  e previous parag
32990 72 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  raphs..*/.int sq
329a0 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29  lite3_sleep(int)
329b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
329c0 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46  F: Name Of The F
329d0 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65  older Holding Te
329e0 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a  mporary Files.**
329f0 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c  .** ^(If this gl
32a00 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73  obal variable is
32a10 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
32a20 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
32a30 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20   is.** the name 
32a40 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b  of a folder (a.k
32a50 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20  .a. directory), 
32a60 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61  then all tempora
32a70 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61  ry files.** crea
32a80 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 68  ted by SQLite wh
32a90 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74  en using a built
32aa0 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  -in [sqlite3_vfs
32ab0 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20   | VFS].** will 
32ac0 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61  be placed in tha
32ad0 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20  t directory.)^  
32ae0 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c  ^If this variabl
32af0 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  e.** is a NULL p
32b00 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
32b10 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73  ite performs a s
32b20 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70  earch for an app
32b30 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70  ropriate.** temp
32b40 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63  orary file direc
32b50 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69  tory..**.** It i
32b60 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65  s not safe to re
32b70 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ad or modify thi
32b80 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f  s variable in mo
32b90 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74  re than one.** t
32ba0 68 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e  hread at a time.
32bb0 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65    It is not safe
32bc0 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69   to read or modi
32bd0 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
32be0 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61  .** if a [databa
32bf0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
32c00 73 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20  s being used at 
32c10 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e  the same time in
32c20 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74   a separate.** t
32c30 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20  hread..** It is 
32c40 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68  intended that th
32c50 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73  is variable be s
32c60 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61  et once.** as pa
32c70 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e  rt of process in
32c80 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
32c90 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69   before any SQLi
32ca0 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  te interface.** 
32cb0 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65  routines have be
32cc0 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68  en called and th
32cd0 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
32ce0 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65   remain unchange
32cf0 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e  d.** thereafter.
32d00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d  .**.** ^The [tem
32d10 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
32d20 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f  y pragma] may mo
32d30 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
32d40 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20  le and cause.** 
32d50 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  it to point to m
32d60 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
32d70 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
32d80 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d  loc].  ^Furtherm
32d90 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d  ore,.** the [tem
32da0 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
32db0 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73  y pragma] always
32dc0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e   assumes that an
32dd0 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74  y string.** that
32de0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70   this variable p
32df0 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64  oints to is held
32e00 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   in memory obtai
32e10 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71  ned from .** [sq
32e20 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e  lite3_malloc] an
32e30 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79  d the pragma may
32e40 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65   attempt to free
32e50 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20   that memory.** 
32e60 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
32e70 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20  ree]..** Hence, 
32e80 69 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  if this variable
32e90 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72   is modified dir
32ea0 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74  ectly, either it
32eb0 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61   should be.** ma
32ec0 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20  de NULL or made 
32ed0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f  to point to memo
32ee0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
32ef0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
32f00 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65  ].** or else the
32f10 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d   use of the [tem
32f20 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
32f30 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64  y pragma] should
32f40 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a   be avoided..*/.
32f50 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68  SQLITE_EXTERN ch
32f60 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70  ar *sqlite3_temp
32f70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a  _directory;../*.
32f80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73  ** CAPI3REF: Tes
32f90 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69  t For Auto-Commi
32fa0 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52  t Mode.** KEYWOR
32fb0 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20  DS: {autocommit 
32fc0 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mode}.**.** ^The
32fd0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74   sqlite3_get_aut
32fe0 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66  ocommit() interf
32ff0 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ace returns non-
33000 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20  zero or.** zero 
33010 69 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 74  if the given dat
33020 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
33030 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e   is or is not in
33040 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   autocommit mode
33050 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ,.** respectivel
33060 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20  y.  ^Autocommit 
33070 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65  mode is on by de
33080 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63  fault..** ^Autoc
33090 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69  ommit mode is di
330a0 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47  sabled by a [BEG
330b0 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  IN] statement..*
330c0 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  * ^Autocommit mo
330d0 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64  de is re-enabled
330e0 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f   by a [COMMIT] o
330f0 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a  r [ROLLBACK]..**
33100 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b  .** If certain k
33110 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f  inds of errors o
33120 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d  ccur on a statem
33130 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c  ent within a mul
33140 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ti-statement.** 
33150 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72  transaction (err
33160 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53  ors including [S
33170 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51  QLITE_FULL], [SQ
33180 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20  LITE_IOERR],.** 
33190 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20  [SQLITE_NOMEM], 
331a0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61  [SQLITE_BUSY], a
331b0 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  nd [SQLITE_INTER
331c0 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a  RUPT]) then the.
331d0 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d  ** transaction m
331e0 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62  ight be rolled b
331f0 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
33200 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79  y.  The only way
33210 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20   to.** find out 
33220 77 68 65 74 68 65 72 20 53 51 4c 69 74 65 20 61  whether SQLite a
33230 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c  utomatically rol
33240 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61  led back the tra
33250 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a  nsaction after.*
33260 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f  * an error is to
33270 20 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69   use this functi
33280 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f  on..**.** If ano
33290 74 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e  ther thread chan
332a0 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d  ges the autocomm
332b0 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65  it status of the
332c0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
332d0 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
332e0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75  is routine is ru
332f0 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nning, then the 
33300 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
33310 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  is undefined..*/
33320 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
33330 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69  _autocommit(sqli
33340 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
33350 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65  PI3REF: Find The
33360 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65   Database Handle
33370 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53   Of A Prepared S
33380 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e  tatement.**.** ^
33390 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68  The sqlite3_db_h
333a0 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20  andle interface 
333b0 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74  returns the [dat
333c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
333d0 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77  ] handle.** to w
333e0 68 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64  hich a [prepared
333f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f   statement] belo
33400 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61  ngs.  ^The [data
33410 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
33420 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
33430 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
33440 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64  e is the same [d
33450 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33460 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  on].** that was 
33470 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
33480 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  nt.** to the [sq
33490 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
334a0 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73  ()] call (or its
334b0 20 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20   variants) that 
334c0 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63  was used to.** c
334d0 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  reate the statem
334e0 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74  ent in the first
334f0 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74   place..*/.sqlit
33500 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68  e3 *sqlite3_db_h
33510 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  andle(sqlite3_st
33520 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
33530 49 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20  I3REF: Find the 
33540 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74  next prepared st
33550 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54  atement.**.** ^T
33560 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65  his interface re
33570 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
33580 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65  to the next [pre
33590 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
335a0 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20   after.** pStmt 
335b0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
335c0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
335d0 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20  nnection] pDb.  
335e0 5e 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c  ^If pStmt is NUL
335f0 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69  L.** then this i
33600 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
33610 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
33620 65 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64  e first prepared
33630 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73   statement.** as
33640 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
33650 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
33660 63 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20  ction pDb.  ^If 
33670 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74  no prepared stat
33680 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69  ement.** satisfi
33690 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e  es the condition
336a0 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
336b0 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55  e, it returns NU
336c0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64  LL..**.** The [d
336d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
336e0 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e  on] pointer D in
336f0 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
33700 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
33710 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65  (D,S)] must refe
33720 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74  r to an open dat
33730 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
33740 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69  ion and in parti
33750 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62  cular must not b
33760 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
33770 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d  ..*/.sqlite3_stm
33780 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  t *sqlite3_next_
33790 73 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44  stmt(sqlite3 *pD
337a0 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  b, sqlite3_stmt 
337b0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
337c0 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74  CAPI3REF: Commit
337d0 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f   And Rollback No
337e0 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62  tification Callb
337f0 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  acks.**.** ^The 
33800 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
33810 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
33820 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
33830 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
33840 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
33850 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
33860 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54  ction is [COMMIT
33870 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a   | committed]..*
33880 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  * ^Any callback 
33890 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
338a0 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
338b0 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a  3_commit_hook().
338c0 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
338d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
338e0 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
338f0 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  n..** ^The sqlit
33900 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
33910 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
33920 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
33930 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f  k.** function to
33940 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
33950 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  ever a transacti
33960 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20  on is [ROLLBACK 
33970 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a  | rolled back]..
33980 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b  ** ^Any callback
33990 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
339a0 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  us call to sqlit
339b0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
339c0 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  ().** for the sa
339d0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
339e0 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
339f0 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41  dden..** ^The pA
33a00 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70  rg argument is p
33a10 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f  assed through to
33a20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a   the callback..*
33a30 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
33a40 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68  ck on a commit h
33a50 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  ook function ret
33a60 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a  urns non-zero,.*
33a70 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69  * then the commi
33a80 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69  t is converted i
33a90 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a  nto a rollback..
33aa0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33ab0 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44  e3_commit_hook(D
33ac0 2c 43 2c 50 29 20 61 6e 64 20 73 71 6c 69 74 65  ,C,P) and sqlite
33ad0 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
33ae0 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73  D,C,P) functions
33af0 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 50  .** return the P
33b00 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74   argument from t
33b10 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
33b20 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
33b30 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20  ction.** on the 
33b40 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
33b50 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72  onnection] D, or
33b60 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65   NULL for.** the
33b70 20 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20   first call for 
33b80 65 61 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e  each function on
33b90 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61   D..**.** The ca
33ba0 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74  llback implement
33bb0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64  ation must not d
33bc0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
33bd0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
33be0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
33bf0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
33c00 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ked the callback
33c10 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a  .  Any actions.*
33c20 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20  * to modify the 
33c30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33c40 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65  ion must be defe
33c50 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72  rred until after
33c60 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69   the.** completi
33c70 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
33c80 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
33c90 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
33ca0 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20  he commit.** or 
33cb0 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e  rollback hook in
33cc0 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65   the first place
33cd0 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
33ce0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
33cf0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
33d00 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
33d10 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
33d20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33d30 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
33d40 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
33d50 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
33d60 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73  ph..**.** ^Regis
33d70 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75  tering a NULL fu
33d80 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20  nction disables 
33d90 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
33da0 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 63 6f  .** ^When the co
33db0 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61  mmit hook callba
33dc0 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ck routine retur
33dd0 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f  ns zero, the [CO
33de0 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69  MMIT].** operati
33df0 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f  on is allowed to
33e00 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c   continue normal
33e10 6c 79 2e 20 20 5e 49 66 20 74 68 65 20 63 6f 6d  ly.  ^If the com
33e20 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75  mit hook.** retu
33e30 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
33e40 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20  en the [COMMIT] 
33e50 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74  is converted int
33e60 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a  o a [ROLLBACK]..
33e70 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b  ** ^The rollback
33e80 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64   hook is invoked
33e90 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74   on a rollback t
33ea0 68 61 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  hat results from
33eb0 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f   a commit.** hoo
33ec0 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d  k returning non-
33ed0 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74  zero, just as it
33ee0 20 77 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61   would be with a
33ef0 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63  ny other rollbac
33f00 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68  k..**.** ^For th
33f10 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
33f20 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61  is API, a transa
33f30 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f  ction is said to
33f40 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f   have been.** ro
33f50 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20  lled back if an 
33f60 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41  explicit "ROLLBA
33f70 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73  CK" statement is
33f80 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a   executed, or.**
33f90 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e   an error or con
33fa0 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61  straint causes a
33fb0 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62  n implicit rollb
33fc0 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a  ack to occur..**
33fd0 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63   ^The rollback c
33fe0 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69  allback is not i
33ff0 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e  nvoked if a tran
34000 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75  saction is.** au
34010 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
34020 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20  ed back because 
34030 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
34040 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
34050 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
34060 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 75  o the [sqlite3_u
34070 70 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e  pdate_hook()] in
34080 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64  terface..*/.void
34090 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74   *sqlite3_commit
340a0 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20  _hook(sqlite3*, 
340b0 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
340c0 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  oid*);.void *sql
340d0 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
340e0 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ok(sqlite3*, voi
340f0 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f  d(*)(void *), vo
34100 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
34110 49 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e  I3REF: Data Chan
34120 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20  ge Notification 
34130 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
34140 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64  ^The sqlite3_upd
34150 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  ate_hook() inter
34160 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
34170 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
34180 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
34190 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
341a0 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20  ion] identified 
341b0 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
341c0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69  ument.** to be i
341d0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
341e0 61 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64  a row is updated
341f0 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  , inserted or de
34200 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63  leted..** ^Any c
34210 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
34220 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
34230 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a  o this function.
34240 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
34250 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34260 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
34270 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  n..**.** ^The se
34280 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
34290 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
342a0 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e  e function to in
342b0 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72  voke when a.** r
342c0 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69  ow is updated, i
342d0 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
342e0 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  ed..** ^The firs
342f0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
34300 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  e callback is a 
34310 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
34320 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  d argument.** to
34330 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
34340 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20  hook()..** ^The 
34350 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20  second callback 
34360 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
34370 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52  of [SQLITE_INSER
34380 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45  T], [SQLITE_DELE
34390 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  TE],.** or [SQLI
343a0 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65  TE_UPDATE], depe
343b0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65  nding on the ope
343c0 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73  ration that caus
343d0 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  ed the callback.
343e0 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ** to be invoked
343f0 2e 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  ..** ^The third 
34400 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d  and fourth argum
34410 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c  ents to the call
34420 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69  back contain poi
34430 6e 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20  nters to the.** 
34440 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62  database and tab
34450 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69  le name containi
34460 6e 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20  ng the affected 
34470 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e  row..** ^The fin
34480 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61  al callback para
34490 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f  meter is the [ro
344a0 77 69 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e  wid] of the row.
344b0 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 61 73 65  .** ^In the case
344c0 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74   of an update, t
344d0 68 69 73 20 69 73 20 74 68 65 20 5b 72 6f 77 69  his is the [rowi
344e0 64 5d 20 61 66 74 65 72 20 74 68 65 20 75 70 64  d] after the upd
344f0 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e  ate takes place.
34500 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64  .**.** ^(The upd
34510 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20  ate hook is not 
34520 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74  invoked when int
34530 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62  ernal system tab
34540 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66  les are.** modif
34550 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65  ied (i.e. sqlite
34560 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69  _master and sqli
34570 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a  te_sequence).)^.
34580 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75  **.** ^In the cu
34590 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61  rrent implementa
345a0 74 69 6f 6e 2c 20 74 68 65 20 75 70 64 61 74 65  tion, the update
345b0 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20   hook.** is not 
345c0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 64 75 70  invoked when dup
345d0 6c 69 63 61 74 69 6f 6e 20 72 6f 77 73 20 61 72  lication rows ar
345e0 65 20 64 65 6c 65 74 65 64 20 62 65 63 61 75 73  e deleted becaus
345f0 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43  e of an.** [ON C
34600 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e  ONFLICT | ON CON
34610 46 4c 49 43 54 20 52 45 50 4c 41 43 45 5d 20 63  FLICT REPLACE] c
34620 6c 61 75 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20  lause.  ^Nor is 
34630 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a  the update hook.
34640 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  ** invoked when 
34650 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
34660 20 75 73 69 6e 67 20 74 68 65 20 5b 74 72 75 6e   using the [trun
34670 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f  cate optimizatio
34680 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65 78 63 65 70  n]..** The excep
34690 74 69 6f 6e 73 20 64 65 66 69 6e 65 64 20 69 6e  tions defined in
346a0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 20   this paragraph 
346b0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20  might change in 
346c0 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65  a future.** rele
346d0 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
346e0 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20  *.** The update 
346f0 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74  hook implementat
34700 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ion must not do 
34710 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
34720 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
34730 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
34740 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
34750 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  d the update hoo
34760 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a  k.  Any actions.
34770 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65  ** to modify the
34780 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
34790 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66  tion must be def
347a0 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65  erred until afte
347b0 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  r the.** complet
347c0 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
347d0 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
347e0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
347f0 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e  the update hook.
34800 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
34810 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
34820 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
34830 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
34840 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
34850 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34860 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
34870 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
34880 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
34890 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  h..**.** ^The sq
348a0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
348b0 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f  k(D,C,P) functio
348c0 6e 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65  n.** returns the
348d0 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d   P argument from
348e0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
348f0 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d  ll.** on the sam
34900 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
34910 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55  ection] D, or NU
34920 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69  LL for.** the fi
34930 72 73 74 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a  rst call on D..*
34940 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
34950 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  e [sqlite3_commi
34960 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73  t_hook()] and [s
34970 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
34980 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  hook()].** inter
34990 66 61 63 65 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  faces..*/.void *
349a0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
349b0 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ook(.  sqlite3*,
349c0 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
349d0 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e   *,int ,char con
349e0 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20  st *,char const 
349f0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
34a00 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a  ,.  void*.);../*
34a10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
34a20 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
34a30 53 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63  Shared Pager Cac
34a40 68 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  he.** KEYWORDS: 
34a50 7b 73 68 61 72 65 64 20 63 61 63 68 65 7d 0a 2a  {shared cache}.*
34a60 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
34a70 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
34a80 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72  isables the shar
34a90 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62  ing of the datab
34aa0 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64  ase cache.** and
34ab0 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72   schema data str
34ac0 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20  uctures between 
34ad0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
34ae0 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f  tion | connectio
34af0 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61  ns].** to the sa
34b00 6d 65 20 64 61 74 61 62 61 73 65 2e 20 53 68 61  me database. Sha
34b10 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
34b20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  if the argument 
34b30 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64  is true.** and d
34b40 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 61  isabled if the a
34b50 72 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73 65  rgument is false
34b60 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65  .)^.**.** ^Cache
34b70 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62   sharing is enab
34b80 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64  led and disabled
34b90 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 70   for an entire p
34ba0 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20  rocess..** This 
34bb0 69 73 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f  is a change as o
34bc0 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
34bd0 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72   3.5.0. In prior
34be0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
34bf0 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20  ite,.** sharing 
34c00 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  was enabled or d
34c10 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68  isabled for each
34c20 20 74 68 72 65 61 64 20 73 65 70 61 72 61 74 65   thread separate
34c30 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ly..**.** ^(The 
34c40 63 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f  cache sharing mo
34c50 64 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69  de set by this i
34c60 6e 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73  nterface effects
34c70 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a   all subsequent.
34c80 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ** calls to [sql
34c90 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
34ca0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
34cb0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
34cc0 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78  open16()]..** Ex
34cd0 69 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  isting database 
34ce0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74  connections cont
34cf0 69 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61  inue use the sha
34d00 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61  ring mode.** tha
34d10 74 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 20  t was in effect 
34d20 61 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79  at the time they
34d30 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 29 5e 0a   were opened.)^.
34d40 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
34d50 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
34d60 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72  LITE_OK] if shar
34d70 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61  ed cache was ena
34d80 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
34d90 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
34da0 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64  .  An [error cod
34db0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f  e] is returned o
34dc0 74 68 65 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a  therwise.)^.**.*
34dd0 2a 20 5e 53 68 61 72 65 64 20 63 61 63 68 65 20  * ^Shared cache 
34de0 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
34df0 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73  efault. But this
34e00 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e   might change in
34e10 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61  .** future relea
34e20 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ses of SQLite.  
34e30 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
34e40 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61  t care about sha
34e50 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74  red.** cache set
34e60 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20  ting should set 
34e70 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a  it explicitly..*
34e80 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20  *.** See Also:  
34e90 5b 53 51 4c 69 74 65 20 53 68 61 72 65 64 2d 43  [SQLite Shared-C
34ea0 61 63 68 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e  ache Mode].*/.in
34eb0 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65  t sqlite3_enable
34ec0 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e  _shared_cache(in
34ed0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
34ee0 52 45 46 3a 20 41 74 74 65 6d 70 74 20 54 6f 20  REF: Attempt To 
34ef0 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79  Free Heap Memory
34f00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34f10 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
34f20 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  ry() interface a
34f30 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20  ttempts to free 
34f40 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65  N bytes.** of he
34f50 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61  ap memory by dea
34f60 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73  llocating non-es
34f70 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61  sential memory a
34f80 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65  llocations.** he
34f90 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61  ld by the databa
34fa0 73 65 20 6c 69 62 72 61 72 79 2e 20 20 20 4d 65  se library.   Me
34fb0 6d 6f 72 79 20 75 73 65 64 20 74 6f 20 63 61 63  mory used to cac
34fc0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70  he database.** p
34fd0 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20  ages to improve 
34fe0 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61  performance is a
34ff0 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e  n example of non
35000 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72  -essential memor
35010 79 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  y..** ^sqlite3_r
35020 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20  elease_memory() 
35030 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
35040 65 72 20 6f 66 20 62 79 74 65 73 20 61 63 74 75  er of bytes actu
35050 61 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77  ally freed,.** w
35060 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f  hich might be mo
35070 72 65 20 6f 72 20 6c 65 73 73 20 74 68 61 6e 20  re or less than 
35080 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65  the amount reque
35090 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  sted..** ^The sq
350a0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
350b0 6d 6f 72 79 28 29 20 72 6f 75 74 69 6e 65 20 69  mory() routine i
350c0 73 20 61 20 6e 6f 2d 6f 70 20 72 65 74 75 72 6e  s a no-op return
350d0 69 6e 67 20 7a 65 72 6f 0a 2a 2a 20 69 66 20 53  ing zero.** if S
350e0 51 4c 69 74 65 20 69 73 20 6e 6f 74 20 63 6f 6d  QLite is not com
350f0 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
35100 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59  TE_ENABLE_MEMORY
35110 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2f  _MANAGEMENT]..*/
35120 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c  .int sqlite3_rel
35130 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29  ease_memory(int)
35140 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35150 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69  F: Impose A Limi
35160 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a  t On Heap Size.*
35170 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35180 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
35190 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
351a0 73 65 74 73 20 61 6e 64 2f 6f 72 20 71 75 65 72  sets and/or quer
351b0 69 65 73 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20  ies the.** soft 
351c0 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f  limit on the amo
351d0 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f  unt of heap memo
351e0 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61  ry that may be a
351f0 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
35200 74 65 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 73  te..** ^SQLite s
35210 74 72 69 76 65 73 20 74 6f 20 6b 65 65 70 20 68  trives to keep h
35220 65 61 70 20 6d 65 6d 6f 72 79 20 75 74 69 6c 69  eap memory utili
35230 7a 61 74 69 6f 6e 20 62 65 6c 6f 77 20 74 68 65  zation below the
35240 20 73 6f 66 74 20 68 65 61 70 0a 2a 2a 20 6c 69   soft heap.** li
35250 6d 69 74 20 62 79 20 72 65 64 75 63 69 6e 67 20  mit by reducing 
35260 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
35270 67 65 73 20 68 65 6c 64 20 69 6e 20 74 68 65 20  ges held in the 
35280 70 61 67 65 20 63 61 63 68 65 0a 2a 2a 20 61 73  page cache.** as
35290 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 73 61   heap memory usa
352a0 67 65 73 20 61 70 70 72 6f 61 63 68 65 73 20 74  ges approaches t
352b0 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68  he limit..** ^Th
352c0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
352d0 74 20 69 73 20 22 73 6f 66 74 22 20 62 65 63 61  t is "soft" beca
352e0 75 73 65 20 65 76 65 6e 20 74 68 6f 75 67 68 20  use even though 
352f0 53 51 4c 69 74 65 20 73 74 72 69 76 65 73 20 74  SQLite strives t
35300 6f 20 73 74 61 79 0a 2a 2a 20 62 65 6c 6f 77 20  o stay.** below 
35310 74 68 65 20 6c 69 6d 69 74 2c 20 69 74 20 77 69  the limit, it wi
35320 6c 6c 20 65 78 63 65 65 64 20 74 68 65 20 6c 69  ll exceed the li
35330 6d 69 74 20 72 61 74 68 65 72 20 74 68 61 6e 20  mit rather than 
35340 67 65 6e 65 72 61 74 65 0a 2a 2a 20 61 6e 20 5b  generate.** an [
35350 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 65 72  SQLITE_NOMEM] er
35360 72 6f 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ror.  In other w
35370 6f 72 64 73 2c 20 74 68 65 20 73 6f 66 74 20 68  ords, the soft h
35380 65 61 70 20 6c 69 6d 69 74 20 0a 2a 2a 20 69 73  eap limit .** is
35390 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a   advisory only..
353a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  **.** ^The retur
353b0 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
353c0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
353d0 69 6d 69 74 36 34 28 29 20 69 73 20 74 68 65 20  imit64() is the 
353e0 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20 73  size of.** the s
353f0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 70  oft heap limit p
35400 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  rior to the call
35410 2e 20 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d  .  ^If the argum
35420 65 6e 74 20 4e 20 69 73 20 6e 65 67 61 74 69 76  ent N is negativ
35430 65 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 63 68 61  e.** then no cha
35440 6e 67 65 20 69 73 20 6d 61 64 65 20 74 6f 20 74  nge is made to t
35450 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
35460 69 74 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  it.  Hence, the 
35470 63 75 72 72 65 6e 74 0a 2a 2a 20 73 69 7a 65 20  current.** size 
35480 6f 66 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  of the soft heap
35490 20 6c 69 6d 69 74 20 63 61 6e 20 62 65 20 64 65   limit can be de
354a0 74 65 72 6d 69 6e 65 64 20 62 79 20 69 6e 76 6f  termined by invo
354b0 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  king.** sqlite3_
354c0 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
354d0 34 28 29 20 77 69 74 68 20 61 20 6e 65 67 61 74  4() with a negat
354e0 69 76 65 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ive argument..**
354f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 72 67 75  .** ^If the argu
35500 6d 65 6e 74 20 4e 20 69 73 20 7a 65 72 6f 20 74  ment N is zero t
35510 68 65 6e 20 74 68 65 20 73 6f 66 74 20 68 65 61  hen the soft hea
35520 70 20 6c 69 6d 69 74 20 69 73 20 64 69 73 61 62  p limit is disab
35530 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  led..**.** ^(The
35540 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
35550 20 69 73 20 6e 6f 74 20 65 6e 66 6f 72 63 65 64   is not enforced
35560 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
35570 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
35580 2a 20 69 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  * if one or more
35590 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f   of following co
355a0 6e 64 69 74 69 6f 6e 73 20 61 72 65 20 74 72 75  nditions are tru
355b0 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
355c0 20 3c 6c 69 3e 20 54 68 65 20 73 6f 66 74 20 68   <li> The soft h
355d0 65 61 70 20 6c 69 6d 69 74 20 69 73 20 73 65 74  eap limit is set
355e0 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c 69   to zero..** <li
355f0 3e 20 4d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74  > Memory account
35600 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 20  ing is disabled 
35610 75 73 69 6e 67 20 61 20 63 6f 6d 62 69 6e 61 74  using a combinat
35620 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ion of the.**   
35630 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66     [sqlite3_conf
35640 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
35650 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c 2e 2e  IG_MEMSTATUS],..
35660 2e 29 20 73 74 61 72 74 2d 74 69 6d 65 20 6f 70  .) start-time op
35670 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20  tion and.**     
35680 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 46   the [SQLITE_DEF
35690 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 20  AULT_MEMSTATUS] 
356a0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
356b0 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 41 6e 20  ion..** <li> An 
356c0 61 6c 74 65 72 6e 61 74 69 76 65 20 70 61 67 65  alternative page
356d0 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
356e0 61 74 69 6f 6e 20 69 73 20 73 70 65 63 69 66 69  ation is specifi
356f0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
35700 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
35710 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
35720 5f 50 43 41 43 48 45 5d 2c 2e 2e 2e 29 2e 0a 2a  _PCACHE],...)..*
35730 2a 20 3c 6c 69 3e 20 54 68 65 20 70 61 67 65 20  * <li> The page 
35740 63 61 63 68 65 20 61 6c 6c 6f 63 61 74 65 73 20  cache allocates 
35750 66 72 6f 6d 20 69 74 73 20 6f 77 6e 20 6d 65 6d  from its own mem
35760 6f 72 79 20 70 6f 6f 6c 20 73 75 70 70 6c 69 65  ory pool supplie
35770 64 0a 2a 2a 20 20 20 20 20 20 62 79 20 5b 73 71  d.**      by [sq
35780 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
35790 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
357a0 45 43 41 43 48 45 5d 2c 2e 2e 2e 29 20 72 61 74  ECACHE],...) rat
357b0 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  her than.**     
357c0 20 66 72 6f 6d 20 74 68 65 20 68 65 61 70 2e 0a   from the heap..
357d0 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
357e0 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20   Beginning with 
357f0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
35800 2e 37 2e 33 2c 20 74 68 65 20 73 6f 66 74 20 68  .7.3, the soft h
35810 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e 66  eap limit is enf
35820 6f 72 63 65 64 0a 2a 2a 20 72 65 67 61 72 64 6c  orced.** regardl
35830 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
35840 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54  r not the [SQLIT
35850 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f  E_ENABLE_MEMORY_
35860 4d 41 4e 41 47 45 4d 45 4e 54 5d 0a 2a 2a 20 63  MANAGEMENT].** c
35870 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
35880 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  on is invoked.  
35890 57 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41  With [SQLITE_ENA
358a0 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47  BLE_MEMORY_MANAG
358b0 45 4d 45 4e 54 5d 2c 0a 2a 2a 20 74 68 65 20 73  EMENT],.** the s
358c0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
358d0 73 20 65 6e 66 6f 72 63 65 64 20 6f 6e 20 65 76  s enforced on ev
358e0 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
358f0 61 74 69 6f 6e 2e 20 20 57 69 74 68 6f 75 74 0a  ation.  Without.
35900 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
35910 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d  E_MEMORY_MANAGEM
35920 45 4e 54 5d 2c 20 74 68 65 20 73 6f 66 74 20 68  ENT], the soft h
35930 65 61 70 20 6c 69 6d 69 74 20 69 73 20 6f 6e 6c  eap limit is onl
35940 79 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20 77 68  y enforced.** wh
35950 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c  en memory is all
35960 6f 63 61 74 65 64 20 62 79 20 74 68 65 20 70 61  ocated by the pa
35970 67 65 20 63 61 63 68 65 2e 20 20 54 65 73 74 69  ge cache.  Testi
35980 6e 67 20 73 75 67 67 65 73 74 73 20 74 68 61 74  ng suggests that
35990 20 62 65 63 61 75 73 65 0a 2a 2a 20 74 68 65 20   because.** the 
359a0 70 61 67 65 20 63 61 63 68 65 20 69 73 20 74 68  page cache is th
359b0 65 20 70 72 65 64 6f 6d 69 6e 61 74 65 20 6d 65  e predominate me
359c0 6d 6f 72 79 20 75 73 65 72 20 69 6e 20 53 51 4c  mory user in SQL
359d0 69 74 65 2c 20 6d 6f 73 74 0a 2a 2a 20 61 70 70  ite, most.** app
359e0 6c 69 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 61  lications will a
359f0 63 68 69 65 76 65 20 61 64 65 71 75 61 74 65 20  chieve adequate 
35a00 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
35a10 65 6e 66 6f 72 63 65 6d 65 6e 74 20 77 69 74 68  enforcement with
35a20 6f 75 74 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  out.** the use o
35a30 66 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  f [SQLITE_ENABLE
35a40 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45  _MEMORY_MANAGEME
35a50 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  NT]..**.** The c
35a60 69 72 63 75 6d 73 74 61 6e 63 65 73 20 75 6e 64  ircumstances und
35a70 65 72 20 77 68 69 63 68 20 53 51 4c 69 74 65 20  er which SQLite 
35a80 77 69 6c 6c 20 65 6e 66 6f 72 63 65 20 74 68 65  will enforce the
35a90 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
35aa0 20 6d 61 79 0a 2a 2a 20 63 68 61 6e 67 65 73 20   may.** changes 
35ab0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
35ac0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  es of SQLite..*/
35ad0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
35ae0 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
35af0 5f 6c 69 6d 69 74 36 34 28 73 71 6c 69 74 65 33  _limit64(sqlite3
35b00 5f 69 6e 74 36 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a  _int64 N);../*.*
35b10 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72  * CAPI3REF: Depr
35b20 65 63 61 74 65 64 20 53 6f 66 74 20 48 65 61 70  ecated Soft Heap
35b30 20 4c 69 6d 69 74 20 49 6e 74 65 72 66 61 63 65   Limit Interface
35b40 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a  .** DEPRECATED.*
35b50 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 64  *.** This is a d
35b60 65 70 72 65 63 61 74 65 64 20 76 65 72 73 69 6f  eprecated versio
35b70 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
35b80 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
35b90 74 36 34 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  t64()].** interf
35ba0 61 63 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ace.  This routi
35bb0 6e 65 20 69 73 20 70 72 6f 76 69 64 65 64 20 66  ne is provided f
35bc0 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
35bd0 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 6f  mpatibility.** o
35be0 6e 6c 79 2e 20 20 41 6c 6c 20 6e 65 77 20 61 70  nly.  All new ap
35bf0 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
35c00 64 20 75 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71  d use the.** [sq
35c10 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
35c20 6c 69 6d 69 74 36 34 28 29 5d 20 69 6e 74 65 72  limit64()] inter
35c30 66 61 63 65 20 72 61 74 68 65 72 20 74 68 61 6e  face rather than
35c40 20 74 68 69 73 20 6f 6e 65 2e 0a 2a 2f 0a 53 51   this one..*/.SQ
35c50 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
35c60 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66  void sqlite3_sof
35c70 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74  t_heap_limit(int
35c80 20 4e 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   N);.../*.** CAP
35c90 49 33 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d  I3REF: Extract M
35ca0 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20  etadata About A 
35cb0 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c  Column Of A Tabl
35cc0 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  e.**.** ^This ro
35cd0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d 65  utine returns me
35ce0 74 61 64 61 74 61 20 61 62 6f 75 74 20 61 20 73  tadata about a s
35cf0 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f  pecific column o
35d00 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  f a specific.** 
35d10 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61  database table a
35d20 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20  ccessible using 
35d30 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
35d40 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
35d50 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68  .** passed as th
35d60 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e  e first function
35d70 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
35d80 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20   ^The column is 
35d90 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
35da0 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20  e second, third 
35db0 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d  and fourth param
35dc0 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73  eters to.** this
35dd0 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 20   function. ^The 
35de0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
35df0 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e   is either the n
35e00 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
35e10 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61  ase.** (i.e. "ma
35e20 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f 72 20  in", "temp", or 
35e30 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61  an attached data
35e40 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67  base) containing
35e50 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a   the specified.*
35e60 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e  * table or NULL.
35e70 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c   ^If it is NULL,
35e80 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68   then all attach
35e90 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72 65  ed databases are
35ea0 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72   searched.** for
35eb0 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67   the table using
35ec0 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69   the same algori
35ed0 74 68 6d 20 75 73 65 64 20 62 79 20 74 68 65 20  thm used by the 
35ee0 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
35ef0 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e  to.** resolve un
35f00 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20  qualified table 
35f10 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a  references..**.*
35f20 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64  * ^The third and
35f30 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
35f40 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
35f50 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c  ion are the tabl
35f60 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  e and column.** 
35f70 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69  name of the desi
35f80 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70  red column, resp
35f90 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65  ectively. Neithe
35fa0 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d  r of these param
35fb0 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20  eters.** may be 
35fc0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74  NULL..**.** ^Met
35fd0 61 64 61 74 61 20 69 73 20 72 65 74 75 72 6e 65  adata is returne
35fe0 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20  d by writing to 
35ff0 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74  the memory locat
36000 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20 74  ions passed as t
36010 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75  he 5th.** and su
36020 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74  bsequent paramet
36030 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ers to this func
36040 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 68  tion. ^Any of th
36050 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d 61  ese arguments ma
36060 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e  y be.** NULL, in
36070 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
36080 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c  corresponding el
36090 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 74  ement of metadat
360a0 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  a is omitted..**
360b0 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74  .** ^(<blockquot
360c0 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
360d0 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
360e0 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72 20 3c  <th> Parameter <
360f0 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54 79  th> Output<br>Ty
36100 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72 69 70  pe <th>  Descrip
36110 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  tion.**.** <tr><
36120 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e  td> 5th <td> con
36130 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 44 61  st char* <td> Da
36140 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c  ta type.** <tr><
36150 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e  td> 6th <td> con
36160 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61  st char* <td> Na
36170 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20 63 6f  me of default co
36180 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
36190 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68  .** <tr><td> 7th
361a0 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20   <td> int       
361b0 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63    <td> True if c
361c0 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20  olumn has a NOT 
361d0 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a  NULL constraint.
361e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20  ** <tr><td> 8th 
361f0 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20  <td> int        
36200 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f   <td> True if co
36210 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20  lumn is part of 
36220 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a  the PRIMARY KEY.
36230 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20  ** <tr><td> 9th 
36240 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20  <td> int        
36250 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f   <td> True if co
36260 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43  lumn is [AUTOINC
36270 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62  REMENT].** </tab
36280 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
36290 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
362a0 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64  e memory pointed
362b0 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61   to by the chara
362c0 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65  cter pointers re
362d0 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a  turned for the.*
362e0 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79  * declaration ty
362f0 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e  pe and collation
36300 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c   sequence is val
36310 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68  id only until th
36320 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74  e next.** call t
36330 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50 49  o any SQLite API
36340 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
36350 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
36360 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75  ed table is actu
36370 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20  ally a view, an 
36380 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
36390 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
363a0 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65  ^If the specifie
363b0 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77  d column is "row
363c0 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f  id", "oid" or "_
363d0 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a  rowid_" and an.*
363e0 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  * [INTEGER PRIMA
363f0 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68  RY KEY] column h
36400 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74  as been explicit
36410 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65  ly declared, the
36420 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20  n the output.** 
36430 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73  parameters are s
36440 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69  et for the expli
36450 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
36460 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68 65 72  olumn. ^(If ther
36470 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69  e is no.** expli
36480 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 5b  citly declared [
36490 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
364a0 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65  KEY] column, the
364b0 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20  n the output.** 
364c0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73  parameters are s
364d0 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  et as follows:.*
364e0 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20  *.** <pre>.**   
364f0 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e    data type: "IN
36500 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f  TEGER".**     co
36510 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
36520 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20  : "BINARY".**   
36530 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a    not null: 0.**
36540 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79       primary key
36550 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20  : 1.**     auto 
36560 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20  increment: 0.** 
36570 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  </pre>)^.**.** ^
36580 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d  (This function m
36590 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d  ay load one or m
365a0 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d  ore schemas from
365b0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e   database files.
365c0 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20   If an.** error 
365d0 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
365e0 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  is process, or i
365f0 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  f the requested 
36600 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a  table or column.
36610 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75  ** cannot be fou
36620 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  nd, an [error co
36630 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  de] is returned 
36640 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  and an error mes
36650 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20  sage left.** in 
36660 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
36670 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65  nnection] (to be
36680 20 72 65 74 72 69 65 76 65 64 20 75 73 69 6e 67   retrieved using
36690 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
366a0 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  )).)^.**.** ^Thi
366b0 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76  s API is only av
366c0 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
366d0 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
366e0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
366f0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
36700 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
36710 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
36720 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a  ymbol defined..*
36730 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61  /.int sqlite3_ta
36740 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64  ble_column_metad
36750 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ata(.  sqlite3 *
36760 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
36770 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e     /* Connection
36780 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
36790 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65  st char *zDbName
367a0 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61  ,        /* Data
367b0 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c  base name or NUL
367c0 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  L */.  const cha
367d0 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20  r *zTableName,  
367e0 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65     /* Table name
367f0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
36800 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20   *zColumnName,  
36810 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65    /* Column name
36820 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74   */.  char const
36830 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20   **pzDataType,  
36840 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63    /* OUTPUT: Dec
36850 6c 61 72 65 64 20 64 61 74 61 20 74 79 70 65 20  lared data type 
36860 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20  */.  char const 
36870 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20  **pzCollSeq,    
36880 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c   /* OUTPUT: Coll
36890 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e  ation sequence n
368a0 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e  ame */.  int *pN
368b0 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20  otNull,         
368c0 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
368d0 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c  True if NOT NULL
368e0 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73   constraint exis
368f0 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72  ts */.  int *pPr
36900 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20  imaryKey,       
36910 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54      /* OUTPUT: T
36920 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61  rue if column pa
36930 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e  rt of PK */.  in
36940 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20  t *pAutoinc     
36950 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
36960 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c  PUT: True if col
36970 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72  umn is auto-incr
36980 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  ement */.);../*.
36990 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61  ** CAPI3REF: Loa
369a0 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a  d An Extension.*
369b0 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
369c0 66 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53 51  face loads an SQ
369d0 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c  Lite extension l
369e0 69 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65 20  ibrary from the 
369f0 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  named file..**.*
36a00 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  * ^The sqlite3_l
36a10 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
36a20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
36a30 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a  ts to load an.**
36a40 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f   SQLite extensio
36a50 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69  n library contai
36a60 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 20  ned in the file 
36a70 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  zFile..**.** ^Th
36a80 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73  e entry point is
36a90 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f   zProc..** ^zPro
36aa0 63 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 77  c may be 0, in w
36ab0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 61  hich case the na
36ac0 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20  me of the entry 
36ad0 70 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75 6c 74  point.** default
36ae0 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 78  s to "sqlite3_ex
36af0 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a  tension_init"..*
36b00 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  * ^The sqlite3_l
36b10 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
36b20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
36b30 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  s.** [SQLITE_OK]
36b40 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
36b50 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
36b60 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73  f something goes
36b70 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61   wrong..** ^If a
36b80 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61  n error occurs a
36b90 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e  nd pzErrMsg is n
36ba0 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a  ot 0, then the.*
36bb0 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  * [sqlite3_load_
36bc0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74  extension()] int
36bd0 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74  erface shall att
36be0 65 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20  empt to.** fill 
36bf0 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 65  *pzErrMsg with e
36c00 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
36c10 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f  t stored in memo
36c20 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66  ry.** obtained f
36c30 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
36c40 6c 6f 63 28 29 5d 2e 20 54 68 65 20 63 61 6c 6c  loc()]. The call
36c50 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ing function.** 
36c60 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73  should free this
36c70 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69   memory by calli
36c80 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
36c90 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65  ()]..**.** ^Exte
36ca0 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75  nsion loading mu
36cb0 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73  st be enabled us
36cc0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
36cd0 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
36ce0 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74  nsion()] prior t
36cf0 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41  o calling this A
36d00 50 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  PI,.** otherwise
36d10 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62   an error will b
36d20 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  e returned..**.*
36d30 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
36d40 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
36d50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
36d60 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
36d70 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20  oad_extension(. 
36d80 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
36d90 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74         /* Load t
36da0 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74  he extension int
36db0 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65 20  o this database 
36dc0 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20  connection */.  
36dd0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
36de0 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66  e,    /* Name of
36df0 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 72   the shared libr
36e00 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65  ary containing e
36e10 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f  xtension */.  co
36e20 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c  nst char *zProc,
36e30 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69      /* Entry poi
36e40 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f  nt.  Derived fro
36e50 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a  m zFile if 0 */.
36e60 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73    char **pzErrMs
36e70 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65  g       /* Put e
36e80 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72  rror message her
36e90 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b  e if not 0 */.);
36ea0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36eb0 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
36ec0 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f  ble Extension Lo
36ed0 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20  ading.**.** ^So 
36ee0 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73  as not to open s
36ef0 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e  ecurity holes in
36f00 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69   older applicati
36f10 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20  ons that are.** 
36f20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64 65  unprepared to de
36f30 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f  al with extensio
36f40 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61  n loading, and a
36f50 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73  s a means of dis
36f60 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73  abling.** extens
36f70 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c  ion loading whil
36f80 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65  e evaluating use
36f90 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74  r-entered SQL, t
36fa0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49  he following API
36fb0 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64 20  .** is provided 
36fc0 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c  to turn the [sql
36fd0 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
36fe0 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d  ion()] mechanism
36ff0 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a   on and off..**.
37000 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f  ** ^Extension lo
37010 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79 20  ading is off by 
37020 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69 63  default. See tic
37030 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20 5e 43  ket #1863..** ^C
37040 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  all the sqlite3_
37050 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
37060 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20  nsion() routine 
37070 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a  with onoff==1.**
37080 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69   to turn extensi
37090 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e  on loading on an
370a0 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f  d call it with o
370b0 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a  noff==0 to turn.
370c0 2a 2a 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61  ** it back off a
370d0 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gain..*/.int sql
370e0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64  ite3_enable_load
370f0 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74  _extension(sqlit
37100 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66  e3 *db, int onof
37110 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
37120 52 45 46 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c  REF: Automatical
37130 6c 79 20 4c 6f 61 64 20 53 74 61 74 69 63 61 6c  ly Load Statical
37140 6c 79 20 4c 69 6e 6b 65 64 20 45 78 74 65 6e 73  ly Linked Extens
37150 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ions.**.** ^This
37160 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
37170 73 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e  s the xEntryPoin
37180 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  t() function to 
37190 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 0a 2a  be invoked for.*
371a0 2a 20 65 61 63 68 20 6e 65 77 20 5b 64 61 74 61  * each new [data
371b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
371c0 20 74 68 61 74 20 69 73 20 63 72 65 61 74 65 64   that is created
371d0 2e 20 20 54 68 65 20 69 64 65 61 20 68 65 72 65  .  The idea here
371e0 20 69 73 20 74 68 61 74 0a 2a 2a 20 78 45 6e 74   is that.** xEnt
371f0 72 79 50 6f 69 6e 74 28 29 20 69 73 20 74 68 65  ryPoint() is the
37200 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 66 6f 72   entry point for
37210 20 61 20 73 74 61 74 69 63 61 6c 6c 79 20 6c 69   a statically li
37220 6e 6b 65 64 20 53 51 4c 69 74 65 20 65 78 74 65  nked SQLite exte
37230 6e 73 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73  nsion.** that is
37240 20 74 6f 20 62 65 20 61 75 74 6f 6d 61 74 69 63   to be automatic
37250 61 6c 6c 79 20 6c 6f 61 64 65 64 20 69 6e 74 6f  ally loaded into
37260 20 61 6c 6c 20 6e 65 77 20 64 61 74 61 62 61 73   all new databas
37270 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a  e connections..*
37280 2a 0a 2a 2a 20 5e 28 45 76 65 6e 20 74 68 6f 75  *.** ^(Even thou
37290 67 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  gh the function 
372a0 70 72 6f 74 6f 74 79 70 65 20 73 68 6f 77 73 20  prototype shows 
372b0 74 68 61 74 20 78 45 6e 74 72 79 50 6f 69 6e 74  that xEntryPoint
372c0 28 29 20 74 61 6b 65 73 0a 2a 2a 20 6e 6f 20 61  () takes.** no a
372d0 72 67 75 6d 65 6e 74 73 20 61 6e 64 20 72 65 74  rguments and ret
372e0 75 72 6e 73 20 76 6f 69 64 2c 20 53 51 4c 69 74  urns void, SQLit
372f0 65 20 69 6e 76 6f 6b 65 73 20 78 45 6e 74 72 79  e invokes xEntry
37300 50 6f 69 6e 74 28 29 20 77 69 74 68 20 74 68 72  Point() with thr
37310 65 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  ee.** arguments 
37320 61 6e 64 20 65 78 70 65 63 74 73 20 61 6e 64 20  and expects and 
37330 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 61  integer result a
37340 73 20 69 66 20 74 68 65 20 73 69 67 6e 61 74 75  s if the signatu
37350 72 65 20 6f 66 20 74 68 65 0a 2a 2a 20 65 6e 74  re of the.** ent
37360 72 79 20 70 6f 69 6e 74 20 77 68 65 72 65 20 61  ry point where a
37370 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
37380 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
37390 65 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 69 6e  e>.** &nbsp;  in
373a0 74 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 0a 2a  t xEntryPoint(.*
373b0 2a 20 26 6e 62 73 70 3b 20 20 20 20 73 71 6c 69  * &nbsp;    sqli
373c0 74 65 33 20 2a 64 62 2c 0a 2a 2a 20 26 6e 62 73  te3 *db,.** &nbs
373d0 70 3b 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72  p;    const char
373e0 20 2a 2a 70 7a 45 72 72 4d 73 67 2c 0a 2a 2a 20   **pzErrMsg,.** 
373f0 26 6e 62 73 70 3b 20 20 20 20 63 6f 6e 73 74 20  &nbsp;    const 
37400 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 61  struct sqlite3_a
37410 70 69 5f 72 6f 75 74 69 6e 65 73 20 2a 70 54 68  pi_routines *pTh
37420 75 6e 6b 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 29  unk.** &nbsp;  )
37430 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
37440 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
37450 20 49 66 20 74 68 65 20 78 45 6e 74 72 79 50 6f   If the xEntryPo
37460 69 6e 74 20 72 6f 75 74 69 6e 65 20 65 6e 63 6f  int routine enco
37470 75 6e 74 65 72 73 20 61 6e 20 65 72 72 6f 72 2c  unters an error,
37480 20 69 74 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20   it should make 
37490 2a 70 7a 45 72 72 4d 73 67 0a 2a 2a 20 70 6f 69  *pzErrMsg.** poi
374a0 6e 74 20 74 6f 20 61 6e 20 61 70 70 72 6f 70 72  nt to an appropr
374b0 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61  iate error messa
374c0 67 65 20 28 6f 62 74 61 69 6e 65 64 20 66 72 6f  ge (obtained fro
374d0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  m [sqlite3_mprin
374e0 74 66 28 29 5d 29 0a 2a 2a 20 61 6e 64 20 72 65  tf()]).** and re
374f0 74 75 72 6e 20 61 6e 20 61 70 70 72 6f 70 72 69  turn an appropri
37500 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
37510 2e 20 20 5e 53 51 4c 69 74 65 20 65 6e 73 75 72  .  ^SQLite ensur
37520 65 73 20 74 68 61 74 20 2a 70 7a 45 72 72 4d 73  es that *pzErrMs
37530 67 0a 2a 2a 20 69 73 20 4e 55 4c 4c 20 62 65 66  g.** is NULL bef
37540 6f 72 65 20 63 61 6c 6c 69 6e 67 20 74 68 65 20  ore calling the 
37550 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 2e 20 20  xEntryPoint().  
37560 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76  ^SQLite will inv
37570 6f 6b 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  oke.** [sqlite3_
37580 66 72 65 65 28 29 5d 20 6f 6e 20 2a 70 7a 45 72  free()] on *pzEr
37590 72 4d 73 67 20 61 66 74 65 72 20 78 45 6e 74 72  rMsg after xEntr
375a0 79 50 6f 69 6e 74 28 29 20 72 65 74 75 72 6e 73  yPoint() returns
375b0 2e 20 20 5e 49 66 20 61 6e 79 0a 2a 2a 20 78 45  .  ^If any.** xE
375c0 6e 74 72 79 50 6f 69 6e 74 28 29 20 72 65 74 75  ntryPoint() retu
375d0 72 6e 73 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  rns an error, th
375e0 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
375f0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
37600 6e 31 36 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  n16()],.** or [s
37610 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
37620 5d 20 63 61 6c 6c 20 74 68 61 74 20 70 72 6f 76  ] call that prov
37630 6f 6b 65 64 20 74 68 65 20 78 45 6e 74 72 79 50  oked the xEntryP
37640 6f 69 6e 74 28 29 20 77 69 6c 6c 20 66 61 69 6c  oint() will fail
37650 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
37660 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78   sqlite3_auto_ex
37670 74 65 6e 73 69 6f 6e 28 58 29 20 77 69 74 68 20  tension(X) with 
37680 61 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 58  an entry point X
37690 20 74 68 61 74 20 69 73 20 61 6c 72 65 61 64 79   that is already
376a0 0a 2a 2a 20 6f 6e 20 74 68 65 20 6c 69 73 74 20  .** on the list 
376b0 6f 66 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74  of automatic ext
376c0 65 6e 73 69 6f 6e 73 20 69 73 20 61 20 68 61 72  ensions is a har
376d0 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 20 5e 4e 6f  mless no-op. ^No
376e0 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20   entry point.** 
376f0 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 6d  will be called m
37700 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 66 6f  ore than once fo
37710 72 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  r each database 
37720 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
37730 69 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a  is opened..**.**
37740 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
37750 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65  te3_reset_auto_e
37760 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a  xtension()]..*/.
37770 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75 74 6f  int sqlite3_auto
37780 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20  _extension(void 
37790 28 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29 28 76  (*xEntryPoint)(v
377a0 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid));../*.** CA
377b0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 75  PI3REF: Reset Au
377c0 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69 6f  tomatic Extensio
377d0 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20  n Loading.**.** 
377e0 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
377f0 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 61 75 74  disables all aut
37800 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e  omatic extension
37810 73 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20  s previously.** 
37820 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
37830 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65   [sqlite3_auto_e
37840 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a  xtension()]..*/.
37850 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
37860 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  et_auto_extensio
37870 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  n(void);../*.** 
37880 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f  The interface to
37890 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
378a0 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20  le mechanism is 
378b0 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64  currently consid
378c0 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78  ered.** to be ex
378d0 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65  perimental.  The
378e0 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74   interface might
378f0 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d   change in incom
37900 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a  patible ways..**
37910 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72   If this is a pr
37920 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64  oblem for you, d
37930 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e  o not use the in
37940 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20  terface at this 
37950 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  time..**.** When
37960 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
37970 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61  le mechanism sta
37980 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c  bilizes, we will
37990 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20   declare the.** 
379a0 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c  interface fixed,
379b0 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65   support it inde
379c0 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65  finitely, and re
379d0 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e  move this commen
379e0 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72  t..*/../*.** Str
379f0 75 63 74 75 72 65 73 20 75 73 65 64 20 62 79 20  uctures used by 
37a00 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
37a10 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74  e interface.*/.t
37a20 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
37a30 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74  lite3_vtab sqlit
37a40 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66  e3_vtab;.typedef
37a50 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
37a60 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74  index_info sqlit
37a70 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74  e3_index_info;.t
37a80 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
37a90 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
37aa0 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  r sqlite3_vtab_c
37ab0 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73  ursor;.typedef s
37ac0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f  truct sqlite3_mo
37ad0 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64  dule sqlite3_mod
37ae0 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ule;../*.** CAPI
37af0 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
37b00 62 6c 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  ble Object.** KE
37b10 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
37b20 6d 6f 64 75 6c 65 20 7b 76 69 72 74 75 61 6c 20  module {virtual 
37b30 74 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a  table module}.**
37b40 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74 75  .** This structu
37b50 72 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63 61  re, sometimes ca
37b60 6c 6c 65 64 20 61 20 22 76 69 72 74 75 61 6c 20  lled a "virtual 
37b70 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a  table module", .
37b80 2a 2a 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ** defines the i
37b90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
37ba0 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
37bb0 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73  es].  .** This s
37bc0 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74  tructure consist
37bd0 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68  s mostly of meth
37be0 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75  ods for the modu
37bf0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72  le..**.** ^A vir
37c00 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
37c10 65 20 69 73 20 63 72 65 61 74 65 64 20 62 79 20  e is created by 
37c20 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70 65 72  filling in a per
37c30 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61  sistent.** insta
37c40 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75  nce of this stru
37c50 63 74 75 72 65 20 61 6e 64 20 70 61 73 73 69 6e  cture and passin
37c60 67 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  g a pointer to t
37c70 68 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20  hat instance.** 
37c80 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
37c90 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20  te_module()] or 
37ca0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
37cb0 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a  module_v2()]..**
37cc0 20 5e 54 68 65 20 72 65 67 69 73 74 72 61 74 69   ^The registrati
37cd0 6f 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c 69 64  on remains valid
37ce0 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 70   until it is rep
37cf0 6c 61 63 65 64 20 62 79 20 61 20 64 69 66 66 65  laced by a diffe
37d00 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f  rent.** module o
37d10 72 20 75 6e 74 69 6c 20 74 68 65 20 5b 64 61 74  r until the [dat
37d20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37d30 5d 20 63 6c 6f 73 65 73 2e 20 20 54 68 65 20 63  ] closes.  The c
37d40 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69  ontent.** of thi
37d50 73 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74  s structure must
37d60 20 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 69 6c   not change whil
37d70 65 20 69 74 20 69 73 20 72 65 67 69 73 74 65 72  e it is register
37d80 65 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64  ed with.** any d
37d90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37da0 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  on..*/.struct sq
37db0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20  lite3_module {. 
37dc0 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
37dd0 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28   int (*xCreate)(
37de0 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a  sqlite3*, void *
37df0 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20  pAux,.          
37e00 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63       int argc, c
37e10 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74  onst char *const
37e20 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20  *argv,.         
37e30 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74        sqlite3_vt
37e40 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61  ab **ppVTab, cha
37e50 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  r**);.  int (*xC
37e60 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a  onnect)(sqlite3*
37e70 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20  , void *pAux,.  
37e80 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
37e90 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61   argc, const cha
37ea0 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20  r *const*argv,. 
37eb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71                sq
37ec0 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56  lite3_vtab **ppV
37ed0 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20  Tab, char**);.  
37ee0 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78  int (*xBestIndex
37ef0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
37f00 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69  pVTab, sqlite3_i
37f10 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69  ndex_info*);.  i
37f20 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74  nt (*xDisconnect
37f30 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
37f40 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
37f50 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65  xDestroy)(sqlite
37f60 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
37f70 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
37f80 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
37f90 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62  ab, sqlite3_vtab
37fa0 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73  _cursor **ppCurs
37fb0 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c  or);.  int (*xCl
37fc0 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ose)(sqlite3_vta
37fd0 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
37fe0 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c  t (*xFilter)(sql
37ff0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
38000 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63  *, int idxNum, c
38010 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53 74  onst char *idxSt
38020 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  r,.             
38030 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c     int argc, sql
38040 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67  ite3_value **arg
38050 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78  v);.  int (*xNex
38060 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  t)(sqlite3_vtab_
38070 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20  cursor*);.  int 
38080 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f  (*xEof)(sqlite3_
38090 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20  vtab_cursor*);. 
380a0 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28   int (*xColumn)(
380b0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
380c0 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f  sor*, sqlite3_co
380d0 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20  ntext*, int);.  
380e0 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71  int (*xRowid)(sq
380f0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
38100 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
38110 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e  4 *pRowid);.  in
38120 74 20 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c  t (*xUpdate)(sql
38130 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74  ite3_vtab *, int
38140 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  , sqlite3_value 
38150 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  **, sqlite3_int6
38160 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42  4 *);.  int (*xB
38170 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  egin)(sqlite3_vt
38180 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
38190 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
381a0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
381b0 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74  .  int (*xCommit
381c0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
381d0 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
381e0 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74  xRollback)(sqlit
381f0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
38200 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75  .  int (*xFindFu
38210 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f  nction)(sqlite3_
38220 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74  vtab *pVtab, int
38230 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61   nArg, const cha
38240 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20  r *zName,.      
38250 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38260 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29   void (**pxFunc)
38270 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
38280 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
38290 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20  lue**),.        
382a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
382b0 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20  oid **ppArg);.  
382c0 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73  int (*xRename)(s
382d0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
382e0 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ab, const char *
382f0 7a 4e 65 77 29 3b 0a 20 20 2f 2a 20 54 68 65 20  zNew);.  /* The 
38300 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
38310 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f  e in version 1 o
38320 66 20 74 68 65 20 73 71 6c 69 74 65 5f 6d 6f 64  f the sqlite_mod
38330 75 6c 65 20 6f 62 6a 65 63 74 2e 20 54 68 6f 73  ule object. Thos
38340 65 20 0a 20 20 2a 2a 20 62 65 6c 6f 77 20 61 72  e .  ** below ar
38350 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20  e for version 2 
38360 61 6e 64 20 67 72 65 61 74 65 72 2e 20 2a 2f 0a  and greater. */.
38370 20 20 69 6e 74 20 28 2a 78 53 61 76 65 70 6f 69    int (*xSavepoi
38380 6e 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  nt)(sqlite3_vtab
38390 20 2a 70 56 54 61 62 2c 20 69 6e 74 29 3b 0a 20   *pVTab, int);. 
383a0 20 69 6e 74 20 28 2a 78 52 65 6c 65 61 73 65 29   int (*xRelease)
383b0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
383c0 56 54 61 62 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  VTab, int);.  in
383d0 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 54 6f 29  t (*xRollbackTo)
383e0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
383f0 56 54 61 62 2c 20 69 6e 74 29 3b 0a 7d 3b 0a 0a  VTab, int);.};..
38400 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
38410 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e  Virtual Table In
38420 64 65 78 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69  dexing Informati
38430 6f 6e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  on.** KEYWORDS: 
38440 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
38450 66 6f 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  fo.**.** The sql
38460 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20  ite3_index_info 
38470 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 69 74  structure and it
38480 73 20 73 75 62 73 74 72 75 63 74 75 72 65 73 20  s substructures 
38490 69 73 20 75 73 65 64 20 61 73 20 70 61 72 74 0a  is used as part.
384a0 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75  ** of the [virtu
384b0 61 6c 20 74 61 62 6c 65 5d 20 69 6e 74 65 72 66  al table] interf
384c0 61 63 65 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69  ace to.** pass i
384d0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20  nformation into 
384e0 61 6e 64 20 72 65 63 65 69 76 65 20 74 68 65 20  and receive the 
384f0 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b  reply from the [
38500 78 42 65 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d  xBestIndex].** m
38510 65 74 68 6f 64 20 6f 66 20 61 20 5b 76 69 72 74  ethod of a [virt
38520 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
38530 5d 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 75  ].  The fields u
38540 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20  nder **Inputs** 
38550 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74  are the.** input
38560 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20  s to xBestIndex 
38570 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c  and are read-onl
38580 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 69  y.  xBestIndex i
38590 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65  nserts its.** re
385a0 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a  sults into the *
385b0 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64  *Outputs** field
385c0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61  s..**.** ^(The a
385d0 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72  Constraint[] arr
385e0 61 79 20 72 65 63 6f 72 64 73 20 57 48 45 52 45  ay records WHERE
385f0 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69   clause constrai
38600 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a  nts of the form:
38610 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
38620 74 65 3e 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70  te>column OP exp
38630 72 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  r</blockquote>.*
38640 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 73  *.** where OP is
38650 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c   =, &lt;, &lt;=,
38660 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e   &gt;, or &gt;=.
38670 29 5e 20 20 5e 28 54 68 65 20 70 61 72 74 69 63  )^  ^(The partic
38680 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73  ular operator is
38690 0a 2a 2a 20 73 74 6f 72 65 64 20 69 6e 20 61 43  .** stored in aC
386a0 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 75  onstraint[].op u
386b0 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 0a  sing one of the.
386c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 44 45 58  ** [SQLITE_INDEX
386d0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 7c  _CONSTRAINT_EQ |
386e0 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
386f0 4e 53 54 52 41 49 4e 54 5f 20 76 61 6c 75 65 73  NSTRAINT_ values
38700 5d 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 69 6e  ].)^.** ^(The in
38710 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
38720 6e 20 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a  n is stored in.*
38730 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  * aConstraint[].
38740 69 43 6f 6c 75 6d 6e 2e 29 5e 20 20 5e 28 61 43  iColumn.)^  ^(aC
38750 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62  onstraint[].usab
38760 6c 65 20 69 73 20 54 52 55 45 20 69 66 20 74 68  le is TRUE if th
38770 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65  e.** expr on the
38780 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65   right-hand side
38790 20 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65   can be evaluate
387a0 64 20 28 61 6e 64 20 74 68 75 73 20 74 68 65 20  d (and thus the 
387b0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73  constraint.** is
387c0 20 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c   usable) and fal
387d0 73 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e  se if it cannot.
387e0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70  )^.**.** ^The op
387f0 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69  timizer automati
38800 63 61 6c 6c 79 20