/ Hex Artifact Content
Login

Artifact 547a44dd4ff4d975e92a645ea2d609e543a83d0f:


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 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e  ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2f20: 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61  ) is called on a
2f30: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f40: 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c  ction] that stil
2f50: 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e  l has.** outstan
2f60: 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73  ding [prepared s
2f70: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f  tatements], [BLO
2f80: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f  B handles], and/
2f90: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  or.** [sqlite3_b
2fa0: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74  ackup] objects t
2fb0: 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53  hen it returns S
2fc0: 51 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65  QLITE_OK but the
2fd0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
2fe0: 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73   of resources is
2ff0: 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
3000: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
3010: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42  atements], [BLOB
3020: 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e   handles],.** an
3030: 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  d [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61  p] objects are a
3050: 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  lso destroyed..*
3060: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c  *.** ^If an [sql
3070: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
3080: 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20  destroyed while 
3090: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
30a0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
30b0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
30c0: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
30d0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
30e0: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
30f0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
3100: 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  C)] and [sqlite3
3110: 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a  _close_v2(C)].**
3120: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
3130: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
3140: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
3150: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
3160: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3170: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
3180: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
3190: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
31a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
31b0: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69  ], and not previ
31c0: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a  ously closed..**
31d0: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
31e0: 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c  3_close() or sql
31f0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
3200: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
3210: 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ter.** argument 
3220: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
3230: 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  -op..*/.int sqli
3240: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
3250: 33 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  3*);.int sqlite3
3260: 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65  _close_v2(sqlite
3270: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  3*);../*.** The 
3280: 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62  type for a callb
3290: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ack function..**
32a0: 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20   This is legacy 
32b0: 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20  and deprecated. 
32c0: 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20   It is included 
32d0: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a  for historical.*
32e0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
32f0: 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d  and is not docum
3300: 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65  ented..*/.typede
3310: 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f  f int (*sqlite3_
3320: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3330: 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72  int,char**, char
3340: 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  **);../*.** CAPI
3350: 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51  3REF: One-Step Q
3360: 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49  uery Execution I
3370: 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54  nterface.**.** T
3380: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3390: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61  ) interface is a
33a0: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61   convenience wra
33b0: 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
33c0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
33d0: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
33e0: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
33f0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
3400: 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77  ],.** that allow
3410: 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
3420: 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65   to run multiple
3430: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53   statements of S
3440: 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61  QL.** without ha
3450: 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f  ving to use a lo
3460: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a  t of C code. .**
3470: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
3480: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
3490: 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d  e runs zero or m
34a0: 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ore UTF-8 encode
34b0: 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  d,.** semicolon-
34c0: 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61  separate SQL sta
34d0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
34e0: 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75  nto its 2nd argu
34f0: 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20  ment,.** in the 
3500: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b  context of the [
3510: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3520: 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61  ion] passed in a
3530: 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67  s its 1st.** arg
3540: 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ument.  ^If the 
3550: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3560: 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67  n of the 3rd arg
3570: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
3580: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
3590: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20  t NULL, then it 
35a0: 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65  is invoked for e
35b0: 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a  ach result row.*
35c0: 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20  * coming out of 
35d0: 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51  the evaluated SQ
35e0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e  L statements.  ^
35f0: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
3600: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   to.** sqlite3_e
3610: 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64  xec() is relayed
3620: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
3630: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  1st argument of 
3640: 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  each.** callback
3650: 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49   invocation.  ^I
3660: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70  f the callback p
3670: 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
3680: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e  3_exec().** is N
3690: 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c  ULL, then no cal
36a0: 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e  lback is ever in
36b0: 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74  voked and result
36c0: 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e   rows are.** ign
36d0: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ored..**.** ^If 
36e0: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
36f0: 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
3700: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3710: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  nts passed into.
3720: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3730: 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f  ), then executio
3740: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
3750: 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73   statement stops
3760: 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65   and.** subseque
3770: 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  nt statements ar
3780: 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20  e skipped.  ^If 
3790: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
37a0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
37b0: 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  c().** is not NU
37c0: 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f  LL then any erro
37d0: 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69  r message is wri
37e0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
37f0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3800: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
3810: 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20  c()] and passed 
3820: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
3830: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a   5th parameter..
3840: 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f  ** To avoid memo
3850: 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70  ry leaks, the ap
3860: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
3870: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
3880: 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65  _free()].** on e
3890: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
38a0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68  ings returned th
38b0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
38c0: 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66  rameter of.** of
38d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38e0: 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20  after the error 
38f0: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
3900: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  s no longer need
3910: 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35  ed..** ^If the 5
3920: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3940: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e  s not NULL and n
3950: 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75  o errors.** occu
3960: 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
3970: 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20  exec() sets the 
3980: 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35  pointer in its 5
3990: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
39a0: 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72  ** NULL before r
39b0: 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
39c0: 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65  ^If an sqlite3_e
39d0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72  xec() callback r
39e0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
39f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3a00: 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  c().** routine r
3a10: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42  eturns SQLITE_AB
3a20: 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f  ORT without invo
3a30: 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63  king the callbac
3a40: 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77  k again and.** w
3a50: 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61  ithout running a
3a60: 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51  ny subsequent SQ
3a70: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
3a80: 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67  .** ^The 2nd arg
3a90: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3aa0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3ab0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73  back function is
3ac0: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
3ad0: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
3ae0: 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33   result.  ^The 3
3af0: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rd argument to t
3b00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3b10: 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73  ).** callback is
3b20: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3b30: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3b40: 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20   obtained as if 
3b50: 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
3b60: 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
3b70: 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f   one for each co
3b80: 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c  lumn.  ^If an el
3b90: 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65  ement of a.** re
3ba0: 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c  sult row is NULL
3bb0: 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   then the corres
3bc0: 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70  ponding string p
3bd0: 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a  ointer for the.*
3be0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
3bf0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e   callback is a N
3c00: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
3c10: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
3c20: 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  to the.** sqlite
3c30: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3c40: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3c50: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3c60: 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a  ings where each.
3c70: 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65  ** entry represe
3c80: 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  nts the name of 
3c90: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65  corresponding re
3ca0: 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f  sult column as o
3cb0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3cc0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
3cd0: 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  name()]..**.** ^
3ce0: 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
3cf0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3d00: 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c  exec() is a NULL
3d10: 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e   pointer, a poin
3d20: 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70  ter.** to an emp
3d30: 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20  ty string, or a 
3d40: 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e  pointer that con
3d50: 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65  tains only white
3d60: 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a  space and/or .**
3d70: 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74   SQL comments, t
3d80: 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65  hen no SQL state
3d90: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61  ments are evalua
3da0: 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61  ted and the data
3db0: 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  base.** is not c
3dc0: 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  hanged..**.** Re
3dd0: 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a  strictions:.**.*
3de0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
3df0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e00: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
3e10: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
3e20: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3e30: 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61  c().**      is a
3e40: 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20   valid and open 
3e50: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3e60: 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  tion]..** <li> T
3e70: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e80: 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64  ust not close [d
3e90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3ea0: 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
3eb0: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74  .**      the 1st
3ec0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3ed0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
3ee0: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
3ef0: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
3f00: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3f10: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d  ation must not m
3f20: 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74  odify the SQL st
3f30: 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73  atement text pas
3f40: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20  sed into.**     
3f50: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3f60: 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78  er of sqlite3_ex
3f70: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
3f80: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
3f90: 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  ning..** </ul>.*
3fa0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
3fb0: 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ec(.  sqlite3*, 
3fc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
3ff0: 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
4000: 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20  char *sql,      
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
4030: 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
4040: 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29   int (*callback)
4050: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
4060: 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43  *,char**),  /* C
4070: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
4080: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20   */.  void *,   
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74   /* 1st argument
40c0: 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a   to callback */.
40d0: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20    char **errmsg 
40e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
4100: 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
4110: 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  n here */.);../*
4120: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
4130: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  sult Codes.** KE
4140: 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f  YWORDS: SQLITE_O
4150: 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  K {error code} {
4160: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
4170: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4180: 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20  t code} {result 
4190: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e  codes}.**.** Man
41a0: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f  y SQLite functio
41b0: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74  ns return an int
41c0: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65  eger result code
41d0: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68   from the set sh
41e0: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f  own.** here in o
41f0: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  rder to indicate
4200: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
4210: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65  ure..**.** New e
4220: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62  rror codes may b
4230: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
4240: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
4250: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  Lite..**.** See 
4260: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
4270: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
4280: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4290: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  ],.** [sqlite3_v
42a0: 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
42b0: 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42  )] [SQLITE_ROLLB
42c0: 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  ACK | result cod
42d0: 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  es]..*/.#define 
42e0: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
42f0: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
4300: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
4310: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
4320: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
4330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
4340: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
4350: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
4360: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
4370: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4380: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
4390: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
43a0: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
43b0: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
43c0: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
43d0: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
43e0: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
43f0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4400: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
4410: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
4420: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
4430: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
4440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4450: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
4460: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
4470: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
4480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4490: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
44a0: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
44b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
44c0: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
44d0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
44e0: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
44f0: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4500: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4510: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
4520: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
4530: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
4540: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
4550: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
4560: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
4570: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
4580: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
4590: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
45a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
45b0: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
45c0: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
45d0: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
45e0: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
45f0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4600: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
4610: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
4620: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
4630: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4640: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
4650: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
4660: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
4670: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
4680: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4690: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
46a0: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
46b0: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
46c0: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
46d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
46e0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
46f0: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4700: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4710: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4720: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
4730: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
4740: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
4750: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
4760: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
4770: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
4780: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
4790: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
47a0: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
47b0: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
47c0: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
47d0: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
47e0: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
47f0: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4800: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4810: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4820: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4830: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
4840: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
4850: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
4860: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
4870: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
4880: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4890: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
48a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48b0: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
48c0: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
48d0: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
48e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
48f0: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4900: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4910: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4920: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
4930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
4940: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
4950: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
4960: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4970: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
4980: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4990: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
49a0: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
49b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
49c0: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
49d0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
49e0: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
49f0: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4a00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4a10: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4a20: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4a30: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4a40: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4a50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
4a60: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20  CE      27   /* 
4a70: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72  Notifications fr
4a80: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
4a90: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4aa0: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32  TE_WARNING     2
4ab0: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20  8   /* Warnings 
4ac0: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4ad0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4ae0: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
4af0: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
4b00: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
4b10: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
4b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b30: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
4b40: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4b50: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
4b60: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
4b70: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
4b80: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
4b90: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
4ba0: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4bb0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4bc0: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20  ded error code} 
4bd0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
4be0: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  codes}.** KEYWOR
4bf0: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4c00: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65  sult code} {exte
4c10: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4c20: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20  s}.**.** In its 
4c30: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
4c40: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50  ation, SQLite AP
4c50: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  I routines retur
4c60: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65  n one of 26 inte
4c70: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ger.** [SQLITE_O
4c80: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
4c90: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
4ca0: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
4cb0: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
4cc0: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
4cd0: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
4ce0: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
4cf0: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
4d00: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
4d10: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
4d20: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
4d30: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
4d40: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
4d50: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
4d60: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
4d70: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
4d80: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64  ersion 3.3.8 and
4d90: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a   later) include.
4da0: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61  ** support for a
4db0: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74  dditional result
4dc0: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76   codes that prov
4dd0: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  ide more detaile
4de0: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  d information.**
4df0: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54   about errors. T
4e00: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
4e10: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61  lt codes are ena
4e20: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
4e30: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74  .** on a per dat
4e40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4e50: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65   basis using the
4e60: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4e70: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
4e80: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a  es()] API..**.**
4e90: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61   Some of the ava
4ea0: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20  ilable extended 
4eb0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4ec0: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a   listed here..**
4ed0: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20   One may expect 
4ee0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
4ef0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4f00: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61  des will be expa
4f10: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e  nd.** over time.
4f20: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
4f30: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65  uses extended re
4f40: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c  sult codes shoul
4f50: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73  d expect.** to s
4f60: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f  ee new result co
4f70: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65  des in future re
4f80: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
4f90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
4fa0: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64  TE_OK result cod
4fb0: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20  e will never be 
4fc0: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69  extended.  It wi
4fd0: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ll always.** be 
4fe0: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f  exactly zero..*/
4ff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5000: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20  IOERR_READ      
5010: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5020: 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a  IOERR | (1<<8)).
5030: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5040: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
5050: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5060: 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OERR | (2<<8)).#
5070: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5080: 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20  ERR_WRITE       
5090: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
50a0: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  ERR | (3<<8)).#d
50b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
50c0: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  RR_FSYNC        
50d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
50e0: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  RR | (4<<8)).#de
50f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5100: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20  R_DIR_FSYNC     
5110: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5120: 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  R | (5<<8)).#def
5130: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5140: 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20  _TRUNCATE       
5150: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5160: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
5170: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5180: 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20  FSTAT           
5190: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
51a0: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
51b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55  e SQLITE_IOERR_U
51c0: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  NLOCK           
51d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
51e0: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
51f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44   SQLITE_IOERR_RD
5200: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5210: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5220: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
5230: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
5240: 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28  ETE            (
5250: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5260: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  10<<8)).#define 
5270: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
5280: 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28  CKED           (
5290: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52a0: 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  11<<8)).#define 
52b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d  SQLITE_IOERR_NOM
52c0: 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28  EM             (
52d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52e0: 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  12<<8)).#define 
52f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43  SQLITE_IOERR_ACC
5300: 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28  ESS            (
5310: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5320: 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  13<<8)).#define 
5330: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45  SQLITE_IOERR_CHE
5340: 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28  CKRESERVEDLOCK (
5350: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5360: 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  14<<8)).#define 
5370: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43  SQLITE_IOERR_LOC
5380: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
5390: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53a0: 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  15<<8)).#define 
53b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f  SQLITE_IOERR_CLO
53c0: 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  SE             (
53d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53e0: 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  16<<8)).#define 
53f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
5400: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28  _CLOSE         (
5410: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5420: 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  17<<8)).#define 
5430: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5440: 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28  OPEN           (
5450: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5460: 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  18<<8)).#define 
5470: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5480: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28  SIZE           (
5490: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54a0: 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  19<<8)).#define 
54b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
54c0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28  LOCK           (
54d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54e0: 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  20<<8)).#define 
54f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5500: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28  MAP            (
5510: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5520: 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  21<<8)).#define 
5530: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45  SQLITE_IOERR_SEE
5540: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
5550: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5560: 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  22<<8)).#define 
5570: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
5580: 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28  ETE_NOENT      (
5590: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
55a0: 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  23<<8)).#define 
55b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41  SQLITE_IOERR_MMA
55c0: 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  P              (
55d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
55e0: 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  24<<8)).#define 
55f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54  SQLITE_IOERR_GET
5600: 54 45 4d 50 50 41 54 48 20 20 20 20 20 20 20 28  TEMPPATH       (
5610: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5620: 32 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  25<<8)).#define 
5630: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e  SQLITE_IOERR_CON
5640: 56 50 41 54 48 20 20 20 20 20 20 20 20 20 20 28  VPATH          (
5650: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5660: 32 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  26<<8)).#define 
5670: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48  SQLITE_LOCKED_SH
5680: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28  AREDCACHE      (
5690: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20  SQLITE_LOCKED | 
56a0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
56b0: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43   SQLITE_BUSY_REC
56c0: 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20  OVERY           
56d0: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c  (SQLITE_BUSY   |
56e0: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
56f0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e  e SQLITE_BUSY_SN
5700: 41 50 53 48 4f 54 20 20 20 20 20 20 20 20 20 20  APSHOT          
5710: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
5720: 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69  |  (2<<8)).#defi
5730: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5740: 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20  EN_NOTEMPDIR    
5750: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5760: 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  EN | (1<<8)).#de
5770: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
5780: 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20  OPEN_ISDIR      
5790: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
57a0: 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OPEN | (2<<8)).#
57b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
57c0: 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20  NTOPEN_FULLPATH 
57d0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
57e0: 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29  NTOPEN | (3<<8))
57f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5800: 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54  CANTOPEN_CONVPAT
5810: 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  H       (SQLITE_
5820: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38  CANTOPEN | (4<<8
5830: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5840: 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20  E_CORRUPT_VTAB  
5850: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5860: 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c  E_CORRUPT | (1<<
5870: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5880: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f  TE_READONLY_RECO
5890: 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c 49  VERY       (SQLI
58a0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31  TE_READONLY | (1
58b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
58c0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41  LITE_READONLY_CA
58d0: 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51  NTLOCK       (SQ
58e0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
58f0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5900: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5910: 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28  ROLLBACK       (
5920: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5930: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
5940: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52  e SQLITE_ABORT_R
5950: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20  OLLBACK         
5960: 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c   (SQLITE_ABORT |
5970: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5980: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5990: 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20  NT_CHECK        
59a0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
59b0: 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  NT | (1<<8)).#de
59c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
59d0: 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f  TRAINT_COMMITHOO
59e0: 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  K   (SQLITE_CONS
59f0: 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29  TRAINT | (2<<8))
5a00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a10: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49  CONSTRAINT_FOREI
5a20: 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  GNKEY   (SQLITE_
5a30: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c  CONSTRAINT | (3<
5a40: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a50: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
5a60: 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c  UNCTION     (SQL
5a70: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5a80: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5a90: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5aa0: 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20  NT_NOTNULL      
5ab0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5ac0: 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  NT | (5<<8)).#de
5ad0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5ae0: 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45  TRAINT_PRIMARYKE
5af0: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5b00: 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29  TRAINT | (6<<8))
5b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b20: 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47  CONSTRAINT_TRIGG
5b30: 45 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ER      (SQLITE_
5b40: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c  CONSTRAINT | (7<
5b50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b60: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55  ITE_CONSTRAINT_U
5b70: 4e 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c  NIQUE       (SQL
5b80: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5b90: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
5ba0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5bb0: 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  NT_VTAB         
5bc0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5bd0: 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  NT | (9<<8)).#de
5be0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
5bf0: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20  CE_RECOVER_WAL  
5c00: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49      (SQLITE_NOTI
5c10: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  CE | (1<<8)).#de
5c20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
5c30: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42  CE_RECOVER_ROLLB
5c40: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49  ACK (SQLITE_NOTI
5c50: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  CE | (2<<8)).#de
5c60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
5c70: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20  ING_AUTOINDEX   
5c80: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e      (SQLITE_WARN
5c90: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f  ING | (1<<8))../
5ca0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
5cb0: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
5cc0: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  en Operations.**
5cd0: 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61  .** These bit va
5ce0: 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lues are intende
5cf0: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65  d for use in the
5d00: 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65  .** 3rd paramete
5d10: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
5d20: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
5d30: 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e  erface and.** in
5d40: 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
5d50: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
5d60: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
5d70: 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  thod..*/.#define
5d80: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
5d90: 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78  DONLY         0x
5da0: 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20  00000001  /* Ok 
5db0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5dc0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5dd0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
5de0: 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78  DWRITE        0x
5df0: 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20  00000002  /* Ok 
5e00: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5e10: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5e20: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
5e30: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78  ATE           0x
5e40: 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20  00000004  /* Ok 
5e50: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5e60: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5e70: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c   SQLITE_OPEN_DEL
5e80: 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78  ETEONCLOSE    0x
5e90: 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53  00000008  /* VFS
5ea0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5eb0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
5ec0: 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78  LUSIVE        0x
5ed0: 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53  00000010  /* VFS
5ee0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5ef0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54   SQLITE_OPEN_AUT
5f00: 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78  OPROXY        0x
5f10: 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53  00000020  /* VFS
5f20: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5f30: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
5f40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5f50: 30 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20  00000040  /* Ok 
5f60: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5f70: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5f80: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d   SQLITE_OPEN_MEM
5f90: 4f 52 59 20 20 20 20 20 20 20 20 20 20 20 30 78  ORY           0x
5fa0: 30 30 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20  00000080  /* Ok 
5fb0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5fc0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5fd0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
5fe0: 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  N_DB          0x
5ff0: 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53  00000100  /* VFS
6000: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6010: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
6020: 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  P_DB          0x
6030: 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53  00000200  /* VFS
6040: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6050: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41   SQLITE_OPEN_TRA
6060: 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78  NSIENT_DB     0x
6070: 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53  00000400  /* VFS
6080: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6090: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
60a0: 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  N_JOURNAL     0x
60b0: 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53  00000800  /* VFS
60c0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
60d0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
60e0: 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  P_JOURNAL     0x
60f0: 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53  00001000  /* VFS
6100: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6110: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42   SQLITE_OPEN_SUB
6120: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78  JOURNAL       0x
6130: 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53  00002000  /* VFS
6140: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6150: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53   SQLITE_OPEN_MAS
6160: 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78  TER_JOURNAL   0x
6170: 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53  00004000  /* VFS
6180: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6190: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d   SQLITE_OPEN_NOM
61a0: 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78  UTEX          0x
61b0: 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20  00008000  /* Ok 
61c0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
61d0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
61e0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c   SQLITE_OPEN_FUL
61f0: 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78  LMUTEX        0x
6200: 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00010000  /* Ok 
6210: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
6220: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
6230: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
6240: 52 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78  REDCACHE      0x
6250: 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00020000  /* Ok 
6260: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
6270: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
6280: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
6290: 56 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78  VATECACHE     0x
62a0: 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00040000  /* Ok 
62b0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
62c0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
62d0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c   SQLITE_OPEN_WAL
62e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
62f0: 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53  00080000  /* VFS
6300: 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73   only */../* Res
6310: 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20  erved:          
6320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6330: 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a  x00F00000 */../*
6340: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
6350: 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73  vice Characteris
6360: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  tics.**.** The x
6370: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
6380: 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20  stics method of 
6390: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
63a0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65  methods].** obje
63b0: 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ct returns an in
63c0: 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61  teger which is a
63d0: 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65   vector of these
63e0: 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65  .** bit values e
63f0: 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68  xpressing I/O ch
6400: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66  aracteristics of
6410: 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67   the mass storag
6420: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
6430: 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20   holds the file 
6440: 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
6450: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
6460: 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a   refers to..**.*
6470: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
6480: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  AP_ATOMIC proper
6490: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
64a0: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
64b0: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
64c0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
64d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
64e0: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
64f0: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
6500: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
6510: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
6520: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
6530: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
6540: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
6550: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
6560: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
6570: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
6580: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
6590: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
65a0: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
65b0: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
65c0: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
65d0: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
65e0: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
65f0: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
6600: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
6610: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
6620: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
6630: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
6640: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
6650: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
6660: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
6670: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
6680: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
6690: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
66a0: 57 72 69 74 65 28 29 2e 20 20 54 68 65 20 53 51  Write().  The SQ
66b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
66c0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70  SAFE_OVERWRITE p
66d0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
66e0: 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f  at.** after rebo
66f0: 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ot following a c
6700: 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f  rash or power lo
6710: 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74  ss, the only byt
6720: 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20  es in a.** file 
6730: 74 68 61 74 20 77 65 72 65 20 77 72 69 74 74 65  that were writte
6740: 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69 63 61  n at the applica
6750: 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74  tion level might
6760: 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a   have changed.**
6770: 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65   and that adjace
6780: 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62  nt bytes, even b
6790: 79 74 65 73 20 77 69 74 68 69 6e 20 74 68 65 20  ytes within the 
67a0: 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a  same sector are.
67b0: 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ** guaranteed to
67c0: 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   be unchanged..*
67d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
67e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20  _IOCAP_ATOMIC   
67f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6800: 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65  00000001.#define
6810: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6820: 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 20  OMIC512         
6830: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a       0x00000002.
6840: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6850: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20  OCAP_ATOMIC1K   
6860: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6870: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
6880: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6890: 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC2K            
68a0: 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64     0x00000008.#d
68b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
68c0: 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20  AP_ATOMIC4K     
68d0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
68e0: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
68f0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6900: 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  8K              
6910: 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66   0x00000020.#def
6920: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6930: 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20  _ATOMIC16K      
6940: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6950: 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  40.#define SQLIT
6960: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
6970: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6980: 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e  x00000080.#defin
6990: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
69a0: 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20  TOMIC64K        
69b0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
69c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
69d0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
69e0: 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30  D            0x0
69f0: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20  0000200.#define 
6a00: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
6a10: 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20  UENTIAL         
6a20: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23      0x00000400.#
6a30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6a40: 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f  CAP_UNDELETABLE_
6a50: 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30  WHEN_OPEN  0x000
6a60: 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00800.#define SQ
6a70: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
6a80: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
6a90: 20 20 30 78 30 30 30 30 31 30 30 30 0a 0a 2f 2a    0x00001000../*
6aa0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
6ab0: 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c  le Locking Level
6ac0: 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  s.**.** SQLite u
6ad0: 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ses one of these
6ae0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6af0: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
6b00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
6b10: 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74  ls it makes to t
6b20: 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  he xLock() and x
6b30: 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73  Unlock() methods
6b40: 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  .** of an [sqlit
6b50: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6b60: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e  bject..*/.#defin
6b70: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f  e SQLITE_LOCK_NO
6b80: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64  NE          0.#d
6b90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6ba0: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20  K_SHARED        
6bb0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6bc0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20  _LOCK_RESERVED  
6bd0: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
6be0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6bf0: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  G       3.#defin
6c00: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58  e SQLITE_LOCK_EX
6c10: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f  CLUSIVE     4../
6c20: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
6c30: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54  ynchronization T
6c40: 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ype Flags.**.** 
6c50: 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f  When SQLite invo
6c60: 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20  kes the xSync() 
6c70: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20  method of an.** 
6c80: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6c90: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75  ods] object it u
6ca0: 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f  ses a combinatio
6cb0: 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e  n of.** these in
6cc0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
6cd0: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
6ce0: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ent..**.** When 
6cf0: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
6d00: 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73  DATAONLY flag is
6d10: 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20   used, it means 
6d20: 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63  that the.** sync
6d30: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20   operation only 
6d40: 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64  needs to flush d
6d50: 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72  ata to mass stor
6d60: 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69  age.  Inode.** i
6d70: 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20  nformation need 
6d80: 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20  not be flushed. 
6d90: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
6da0: 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c  r bits of the fl
6db0: 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49  ag.** equal SQLI
6dc0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20  TE_SYNC_NORMAL, 
6dd0: 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73  that means to us
6de0: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6df0: 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49   semantics..** I
6e00: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
6e10: 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49   bits equal SQLI
6e20: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68  TE_SYNC_FULL, th
6e30: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75  at means.** to u
6e40: 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c  se Mac OS X styl
6e50: 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65  e fullsync inste
6e60: 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a  ad of fsync()..*
6e70: 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66  *.** Do not conf
6e80: 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53  use the SQLITE_S
6e90: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
6ea0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6eb0: 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68  flags.** with th
6ec0: 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  e [PRAGMA synchr
6ed0: 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e  onous]=NORMAL an
6ee0: 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  d [PRAGMA synchr
6ef0: 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73  onous]=FULL.** s
6f00: 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73  ettings.  The [s
6f10: 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d  ynchronous pragm
6f20: 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68  a] determines wh
6f30: 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a  en calls to the.
6f40: 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74  ** xSync VFS met
6f50: 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70  hod occur and ap
6f60: 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20  plies uniformly 
6f70: 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66  across all platf
6f80: 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  orms..** The SQL
6f90: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
6fa0: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
6fb0: 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72  FULL flags deter
6fc0: 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72  mine how.** ener
6fd0: 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75  getic or rigorou
6fe0: 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68  s or forceful th
6ff0: 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  e sync operation
7000: 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c  s are and.** onl
7010: 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65  y make a differe
7020: 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66  nce on Mac OSX f
7030: 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53  or the default S
7040: 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28  QLite code..** (
7050: 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20  Third-party VFS 
7060: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7070: 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20  might also make 
7080: 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a  the distinction.
7090: 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54  ** between SQLIT
70a0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
70b0: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
70c0: 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68  LL, but among th
70d0: 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73  e.** operating s
70e0: 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20  ystems natively 
70f0: 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
7100: 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53  ite, only Mac OS
7110: 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74  X.** cares about
7120: 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e   the difference.
7130: 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ).*/.#define SQL
7140: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
7150: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23         0x00002.#
7160: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
7170: 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20  NC_FULL         
7180: 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65   0x00003.#define
7190: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
71a0: 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30  AONLY      0x000
71b0: 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
71c0: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
71d0: 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c   Open File Handl
71e0: 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69  e.**.** An [sqli
71f0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
7200: 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f   represents an o
7210: 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20  pen file in the 
7220: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
7230: 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20   | OS interface 
7240: 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64  layer].  Individ
7250: 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ual OS interface
7260: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
7270: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74  ons will.** want
7280: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69   to subclass thi
7290: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65  s object by appe
72a0: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c  nding additional
72b0: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74   fields.** for t
72c0: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54  heir own use.  T
72d0: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72  he pMethods entr
72e0: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  y is a pointer t
72f0: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
7300: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
7310: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
7320: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72   methods for per
7330: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f  forming.** I/O o
7340: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
7350: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74   open file..*/.t
7360: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
7370: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74  lite3_file sqlit
7380: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20  e3_file;.struct 
7390: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20  sqlite3_file {. 
73a0: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
73b0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
73c0: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20   *pMethods;  /* 
73d0: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f  Methods for an o
73e0: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a  pen file */.};..
73f0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7400: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c  OS Interface Fil
7410: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64  e Virtual Method
7420: 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45  s Object.**.** E
7430: 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64  very file opened
7440: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
7450: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
7460: 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a  od populates an.
7470: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7480: 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f  ] object (or, mo
7490: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73  re commonly, a s
74a0: 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a  ubclass of the.*
74b0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
74c0: 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20   object) with a 
74d0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
74e0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
74f0: 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  bject..** This o
7500: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
7510: 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74  e methods used t
7520: 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
7530: 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  s operations.** 
7540: 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e  against the open
7550: 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65   file represente
7560: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
7570: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a  3_file] object..
7580: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71  **.** If the [sq
7590: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
75a0: 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65   method sets the
75b0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
75c0: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a  ethods element .
75d0: 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ** to a non-NULL
75e0: 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74   pointer, then t
75f0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  he sqlite3_io_me
7600: 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74  thods.xClose met
7610: 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e  hod.** may be in
7620: 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68  voked even if th
7630: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7640: 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74  Open] reported t
7650: 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20  hat it failed.  
7660: 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20  The.** only way 
7670: 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c  to prevent a cal
7680: 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c  l to xClose foll
7690: 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b  owing a failed [
76a0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
76b0: 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65  n].** is for the
76c0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
76d0: 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20  pen] to set the 
76e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
76f0: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a  thods element.**
7700: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
7710: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
7720: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
7730: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
7740: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
7750: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
7760: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
7770: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
7780: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
7790: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
77a0: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
77b0: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
77c0: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
77d0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
77e0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
77f0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
7800: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
7810: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
7820: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
7830: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
7840: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
7850: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
7860: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
7870: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
7880: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
7890: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
78a0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
78b0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
78c0: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
78d0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
78e0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
78f0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7900: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
7910: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7920: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
7930: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
7940: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
7950: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
7960: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
7970: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
7980: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
7990: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
79a0: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
79b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
79c0: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
79d0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
79e0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
79f0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
7a00: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
7a10: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
7a20: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
7a30: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
7a40: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
7a50: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
7a60: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
7a70: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
7a80: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
7a90: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
7aa0: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
7ab0: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
7ac0: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7ad0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
7ae0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
7af0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
7b00: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7b10: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
7b20: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
7b30: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
7b40: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
7b50: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
7b60: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
7b70: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
7b80: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
7b90: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
7ba0: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
7bb0: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
7bc0: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
7bd0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
7be0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
7bf0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
7c00: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
7c10: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
7c20: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
7c30: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
7c40: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
7c50: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
7c60: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
7c70: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
7c80: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
7c90: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
7ca0: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
7cb0: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
7cc0: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
7cd0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
7ce0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
7cf0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
7d00: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
7d10: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
7d20: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
7d30: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
7d40: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
7d50: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
7d60: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
7d70: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
7d80: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
7d90: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
7da0: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
7db0: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
7dc0: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
7dd0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
7de0: 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  .  VFS implement
7df0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a  ations should.**
7e00: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
7e10: 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69  NOTFOUND] for fi
7e20: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64  le control opcod
7e30: 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  es that they do 
7e40: 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65  not.** recognize
7e50: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
7e60: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
7e70: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
7e80: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
7e90: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
7ea0: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
7eb0: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
7ec0: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
7ed0: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
7ee0: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
7ef0: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
7f00: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
7f10: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
7f20: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
7f30: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
7f40: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
7f50: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
7f60: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
7f70: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
7f80: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
7f90: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
7fa0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7fb0: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
7fc0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7fd0: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
7fe0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7ff0: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
8000: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8010: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
8020: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8030: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
8040: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8050: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
8060: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8070: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
8080: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8090: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
80a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
80b0: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
80c0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
80d0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
80e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
80f0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
8100: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
8110: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8120: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
8130: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
8140: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
8150: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
8160: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
8170: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
8180: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
8190: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
81a0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
81b0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
81c0: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
81d0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
81e0: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
81f0: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
8200: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
8210: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
8220: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
8230: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
8240: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
8250: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
8260: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
8270: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
8280: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
8290: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
82a0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
82b0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
82c0: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
82d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
82e0: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
82f0: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
8300: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
8310: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
8320: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
8330: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
8340: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
8350: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
8360: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
8370: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
8380: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
8390: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
83a0: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
83b0: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
83c0: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
83d0: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
83e0: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
83f0: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
8400: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
8410: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
8420: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
8430: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
8440: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
8450: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
8460: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
8470: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
8480: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
8490: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
84a0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
84b0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
84c0: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
84d0: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
84e0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
84f0: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
8500: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
8510: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
8520: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
8530: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
8540: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
8550: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
8560: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8570: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
8580: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
8590: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
85a0: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
85b0: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
85c0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
85d0: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
85e0: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
85f0: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8600: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
8610: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
8620: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8630: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
8640: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8650: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
8660: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
8670: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8680: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
8690: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
86a0: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
86b0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
86c0: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
86d0: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
86e0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
86f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
8700: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
8710: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8720: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8730: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8740: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
8750: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29    int (*xShmMap)
8760: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8770: 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73  int iPg, int pgs
8780: 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c  z, int, void vol
8790: 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20  atile**);.  int 
87a0: 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69  (*xShmLock)(sqli
87b0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
87c0: 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e  ffset, int n, in
87d0: 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64  t flags);.  void
87e0: 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28   (*xShmBarrier)(
87f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8800: 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61    int (*xShmUnma
8810: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
8820: 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67  , int deleteFlag
8830: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
8840: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
8850: 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f  for version 2 */
8860: 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29  .  int (*xFetch)
8870: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8880: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
8890: 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76  fst, int iAmt, v
88a0: 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74  oid **pp);.  int
88b0: 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c   (*xUnfetch)(sql
88c0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
88d0: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
88e0: 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20   void *p);.  /* 
88f0: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8900: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8910: 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64  ion 3 */.  /* Ad
8920: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
8930: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
8940: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
8950: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
8960: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
8970: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
8980: 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  codes.**.** Thes
8990: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
89a0: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
89b0: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
89c0: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
89d0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
89e0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
89f0: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
8a00: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8a10: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
8a20: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ace..**.** The [
8a30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
8a40: 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69  KSTATE] opcode i
8a50: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
8a60: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
8a70: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
8a80: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8a90: 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68  thod to write th
8aa0: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20  e current state 
8ab0: 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28  of.** the lock (
8ac0: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c  one of [SQLITE_L
8ad0: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49  OCK_NONE], [SQLI
8ae0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
8af0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  .** [SQLITE_LOCK
8b00: 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c  _RESERVED], [SQL
8b10: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
8b20: 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f  ], or [SQLITE_LO
8b30: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a  CK_EXCLUSIVE]).*
8b40: 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65  * into an intege
8b50: 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20  r that the pArg 
8b60: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
8b70: 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c  to. This capabil
8b80: 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64  ity.** is used d
8b90: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e  uring testing an
8ba0: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  d only needs to 
8bb0: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65  be supported whe
8bc0: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a  n SQLITE_TEST.**
8bd0: 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20   is defined..** 
8be0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  <ul>.** <li>[[SQ
8bf0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
8c00: 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  HINT]].** The [S
8c10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
8c20: 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73  _HINT] opcode is
8c30: 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20   used by SQLite 
8c40: 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a  to give the VFS.
8c50: 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20  ** layer a hint 
8c60: 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65  of how large the
8c70: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
8c80: 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64  ill grow to be d
8c90: 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72  uring the.** cur
8ca0: 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  rent transaction
8cb0: 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20  .  This hint is 
8cc0: 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74  not guaranteed t
8cd0: 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75  o be accurate bu
8ce0: 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e  t it.** is often
8cf0: 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64   close.  The und
8d00: 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68  erlying VFS migh
8d10: 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61  t choose to prea
8d20: 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65  llocate database
8d30: 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62  .** file space b
8d40: 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e  ased on this hin
8d50: 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65  t in order to he
8d60: 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65  lp writes to the
8d70: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
8d80: 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a  e run faster..**
8d90: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
8da0: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
8db0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
8dc0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
8dd0: 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  IZE] opcode is u
8de0: 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74  sed to request t
8df0: 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65  hat the VFS.** e
8e00: 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63  xtends and trunc
8e10: 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ates the databas
8e20: 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73  e file in chunks
8e30: 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69   of a size speci
8e40: 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75  fied.** by the u
8e50: 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ser. The fourth 
8e60: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
8e70: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8e80: 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20  l()] should .** 
8e90: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65  point to an inte
8ea0: 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63  ger (type int) c
8eb0: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65  ontaining the ne
8ec0: 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20  w chunk-size to 
8ed0: 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e  use.** for the n
8ee0: 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73  ominated databas
8ef0: 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61  e. Allocating da
8f00: 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63  tabase file spac
8f10: 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68  e in large.** ch
8f20: 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74  unks (say 1MB at
8f30: 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65   a time), may re
8f40: 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d  duce file-system
8f50: 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61   fragmentation a
8f60: 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65  nd.** improve pe
8f70: 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d  rformance on som
8f80: 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a  e systems..**.**
8f90: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8fa0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
8fb0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
8fc0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
8fd0: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
8fe0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
8ff0: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
9000: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
9010: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
9020: 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69  ted with a parti
9030: 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a  cular database.*
9040: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53  * connection.  S
9050: 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ee the [sqlite3_
9060: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
9070: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
9080: 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
9090: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
90a0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
90b0: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
90c0: 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  ED]].** ^(The [S
90d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
90e0: 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65  _OMITTED] opcode
90f0: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
9100: 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53  ternally by.** S
9110: 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74  QLite and sent t
9120: 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70  o all VFSes in p
9130: 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74  lace of a call t
9140: 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  o the xSync meth
9150: 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64  od.** when the d
9160: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
9170: 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73  on has [PRAGMA s
9180: 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20  ynchronous] set 
9190: 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d  to OFF.)^.** Som
91a0: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
91b0: 53 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69  Ses need this si
91c0: 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f  gnal in order to
91d0: 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74   operate correct
91e0: 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47  ly.** when [PRAG
91f0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
9200: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
9210: 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c  ous=OFF] is set,
9220: 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46   but most .** VF
9230: 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  Ses do not need 
9240: 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20  this signal and 
9250: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
9260: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
9270: 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  de..** Applicati
9280: 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  ons should not c
9290: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  all [sqlite3_fil
92a0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
92b0: 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65  h this.** opcode
92c0: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
92d0: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
92e0: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
92f0: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a  ecialized VFSes.
9300: 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69  ** that do requi
9310: 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c  re it.  .**.** <
9320: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9330: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
9340: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
9350: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
9360: 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20  V_RETRY] opcode 
9370: 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
9380: 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a  gure automatic.*
9390: 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61  * retry counts a
93a0: 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72  nd intervals for
93b0: 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f   certain disk I/
93c0: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72  O operations for
93d0: 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20   the.** windows 
93e0: 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74  [VFS] in order t
93f0: 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74  o provide robust
9400: 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73  ness in the pres
9410: 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d  ence of.** anti-
9420: 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20  virus programs. 
9430: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
9440: 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c   windows VFS wil
9450: 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61  l retry file rea
9460: 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65  d,.** file write
9470: 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74  , and file delet
9480: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20  e operations up 
9490: 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74  to 10 times, wit
94a0: 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20  h a delay.** of 
94b0: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
94c0: 62 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74  before the first
94d0: 20 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20   retry and with 
94e0: 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61  the delay increa
94f0: 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64  sing.** by an ad
9500: 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c  ditional 25 mill
9510: 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61  iseconds with ea
9520: 63 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65  ch subsequent re
9530: 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  try.  This.** op
9540: 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73  code allows thes
9550: 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30  e two values (10
9560: 20 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20   retries and 25 
9570: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
9580: 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20  delay).** to be 
9590: 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76  adjusted.  The v
95a0: 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65  alues are change
95b0: 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61  d for all databa
95c0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
95d0: 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  * within the sam
95e0: 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20  e process.  The 
95f0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
9600: 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61  inter to an arra
9610: 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65  y of two.** inte
9620: 67 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66  gers where the f
9630: 69 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74  irst integer i t
9640: 68 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75  he new retry cou
9650: 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nt and the secon
9660: 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20  d.** integer is 
9670: 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65  the delay.  If e
9680: 69 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73  ither integer is
9690: 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
96a0: 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69  the setting.** i
96b0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75  s not changed bu
96c0: 74 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72  t instead the pr
96d0: 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61  ior value of tha
96e0: 74 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69  t setting is wri
96f0: 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  tten.** into the
9700: 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c   array entry, al
9710: 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65  lowing the curre
9720: 6e 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67  nt retry setting
9730: 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72  s to be.** inter
9740: 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44  rogated.  The zD
9750: 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  bName parameter 
9760: 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  is ignored..**.*
9770: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9780: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
9790: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
97a0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
97b0: 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20  _WAL] opcode is 
97c0: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
97d0: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
97e0: 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72  istent [WAL | Wr
97f0: 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73  ite Ahead Log] s
9800: 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61  etting.  By defa
9810: 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61  ult, the auxilia
9820: 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61  ry.** write ahea
9830: 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64  d log and shared
9840: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73   memory files us
9850: 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69  ed for transacti
9860: 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72  on control.** ar
9870: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
9880: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
9890: 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69   latest connecti
98a0: 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  on to the databa
98b0: 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53  se.** closes.  S
98c0: 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e  etting persisten
98d0: 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65  t WAL mode cause
98e0: 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f  s those files to
98f0: 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a   persist after.*
9900: 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73  * close.  Persis
9910: 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69  ting the files i
9920: 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74  s useful when ot
9930: 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68  her processes th
9940: 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76  at do not.** hav
9950: 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69  e write permissi
9960: 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74  on on the direct
9970: 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ory containing t
9980: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9990: 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64   want.** to read
99a0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
99b0: 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61  le, as the WAL a
99c0: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
99d0: 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73   files must exis
99e0: 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f  t.** in order fo
99f0: 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  r the database t
9a00: 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20  o be readable.  
9a10: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
9a20: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
9a30: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9a40: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
9a50: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
9a60: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
9a70: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
9a80: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
9a90: 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  isable persisten
9aa0: 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20  t WAL mode or 1 
9ab0: 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73  to enable persis
9ac0: 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65  tent.** WAL mode
9ad0: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
9ae0: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
9af0: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
9b00: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
9b10: 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65  .** WAL persiste
9b20: 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  nce setting..**.
9b30: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9b40: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
9b50: 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e  OVERWRITE]].** ^
9b60: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9b70: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
9b80: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
9b90: 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20   used to set or 
9ba0: 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72  query the.** per
9bb0: 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61  sistent "powersa
9bc0: 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72  fe-overwrite" or
9bd0: 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e   "PSOW" setting.
9be0: 20 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69    The PSOW setti
9bf0: 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73  ng.** determines
9c00: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43   the [SQLITE_IOC
9c10: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
9c20: 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74  RWRITE] bit of t
9c30: 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61  he.** xDeviceCha
9c40: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
9c50: 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68  hods. The fourth
9c60: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
9c70: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9c80: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68  ontrol()] for th
9c90: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64  is opcode should
9ca0: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
9cb0: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20   an integer..** 
9cc0: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20  That integer is 
9cd0: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72  0 to disable zer
9ce0: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72  o-damage mode or
9cf0: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72   1 to enable zer
9d00: 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65  o-damage.** mode
9d10: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
9d20: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
9d30: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
9d40: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
9d50: 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20  .** zero-damage 
9d60: 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a  mode setting..**
9d70: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9d80: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
9d90: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
9da0: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
9db0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e  TE] opcode is in
9dc0: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
9dd0: 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a  after opening.**
9de0: 20 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63   a write transac
9df0: 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  tion to indicate
9e00: 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74   that, unless it
9e10: 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   is rolled back 
9e20: 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73  for some.** reas
9e30: 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64  on, the entire d
9e40: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c  atabase file wil
9e50: 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  l be overwritten
9e60: 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20   by the current 
9e70: 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  .** transaction.
9e80: 20 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79   This is used by
9e90: 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f   VACUUM operatio
9ea0: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ns..**.** <li>[[
9eb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
9ec0: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  NAME]].** ^The [
9ed0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
9ee0: 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e  NAME] opcode can
9ef0: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
9f00: 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a  in the names of.
9f10: 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69  ** all [VFSes] i
9f20: 6e 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e  n the VFS stack.
9f30: 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20    The names are 
9f40: 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73  of all VFS shims
9f50: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61   and the.** fina
9f60: 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56  l bottom-level V
9f70: 46 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69  FS are written i
9f80: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
9f90: 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71  ned from .** [sq
9fa0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
9fb0: 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69  and the result i
9fc0: 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20  s stored in the 
9fd0: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a  char* variable.*
9fe0: 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74  * that the fourt
9ff0: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b  h parameter of [
a000: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
a010: 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74  trol()] points t
a020: 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72  o..** The caller
a030: 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
a040: 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20  for freeing the 
a050: 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65  memory when done
a060: 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c  .  As with.** al
a070: 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61  l file-control a
a080: 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73  ctions, there is
a090: 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68   no guarantee th
a0a0: 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74  at this will act
a0b0: 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74  ually.** do anyt
a0c0: 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73  hing.  Callers s
a0d0: 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65  hould initialize
a0e0: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
a0f0: 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a  ble to a NULL.**
a100: 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65   pointer in case
a110: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
a120: 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d  ol is not implem
a130: 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c  ented.  This fil
a140: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20  e-control.** is 
a150: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61  intended for dia
a160: 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79  gnostic use only
a170: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a180: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a190: 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72  A]].** ^Whenever
a1a0: 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74   a [PRAGMA] stat
a1b0: 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c  ement is parsed,
a1c0: 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54   an [SQLITE_FCNT
a1d0: 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69  L_PRAGMA] .** fi
a1e0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65  le control is se
a1f0: 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b  nt to the open [
a200: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
a210: 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69  ject correspondi
a220: 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74  ng.** to the dat
a230: 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68  abase file to wh
a240: 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73  ich the pragma s
a250: 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e  tatement refers.
a260: 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a   ^The argument.*
a270: 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45  * to the [SQLITE
a280: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
a290: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61  ile control is a
a2a0: 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f  n array of.** po
a2b0: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
a2c0: 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68  s (char**) in wh
a2d0: 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ich the second e
a2e0: 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72  lement of the ar
a2f0: 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ray.** is the na
a300: 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61  me of the pragma
a310: 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65   and the third e
a320: 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72  lement is the ar
a330: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
a340: 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20   pragma or NULL 
a350: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61  if the pragma ha
a360: 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20  s no argument.  
a370: 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72  ^The handler for
a380: 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46   an.** [SQLITE_F
a390: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
a3a0: 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70  e control can op
a3b0: 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68  tionally make th
a3c0: 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a  e first element.
a3d0: 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a  ** of the char**
a3e0: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20   argument point 
a3f0: 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61  to a string obta
a400: 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
a410: 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a  e3_mprintf()].**
a420: 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65   or the equivale
a430: 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69  nt and that stri
a440: 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74  ng will become t
a450: 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65  he result of the
a460: 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68   pragma or.** th
a470: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
a480: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61  if the pragma fa
a490: 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20  ils. ^If the.** 
a4a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a4b0: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
a4c0: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ol returns [SQLI
a4d0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
a4e0: 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50  en normal .** [P
a4f0: 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e  RAGMA] processin
a500: 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49  g continues.  ^I
a510: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
a520: 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66  NTL_PRAGMA].** f
a530: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
a540: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
a550: 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72   then the parser
a560: 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
a570: 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e  e.** VFS has han
a580: 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20  dled the PRAGMA 
a590: 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70  itself and the p
a5a0: 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20  arser generates 
a5b0: 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61  a no-op.** prepa
a5c0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  red statement.  
a5d0: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
a5e0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
a5f0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
a600: 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74  ns.** any result
a610: 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e   code other than
a620: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
a630: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
a640: 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  ], that means.**
a650: 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e   that the VFS en
a660: 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72  countered an err
a670: 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e  or while handlin
a680: 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61  g the [PRAGMA] a
a690: 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  nd the.** compil
a6a0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41  ation of the PRA
a6b0: 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61  GMA fails with a
a6c0: 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b  n error.  ^The [
a6d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a6e0: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  GMA].** file con
a6f0: 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74  trol occurs at t
a700: 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
a710: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
a720: 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f   analysis and so
a730: 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74  .** it is able t
a740: 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74  o override built
a750: 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  -in [PRAGMA] sta
a760: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c  tements..**.** <
a770: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
a780: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a  L_BUSYHANDLER]].
a790: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
a7a0: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
a7b0: 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72  R].** file-contr
a7c0: 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ol may be invoke
a7d0: 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74  d by SQLite on t
a7e0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
a7f0: 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74   handle.** short
a800: 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f  ly after it is o
a810: 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74  pened in order t
a820: 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74  o provide a cust
a830: 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65  om VFS with acce
a840: 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e  ss.** to the con
a850: 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61  nections busy-ha
a860: 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  ndler callback. 
a870: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
a880: 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a  of type (void **
a890: 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20  ).** - an array 
a8a0: 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20  of two (void *) 
a8b0: 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73  values. The firs
a8c0: 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61  t (void *) actua
a8d0: 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f  lly points.** to
a8e0: 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
a8f0: 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69  ype (int (*)(voi
a900: 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20  d *)). In order 
a910: 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f  to invoke the co
a920: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73  nnections.** bus
a930: 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20  y-handler, this 
a940: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
a950: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
a960: 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64  the second (void
a970: 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72   *) in.** the ar
a980: 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ray as the only 
a990: 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20  argument. If it 
a9a0: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
a9b0: 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61  , then the opera
a9c0: 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
a9d0: 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74  e retried. If it
a9e0: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74   returns zero, t
a9f0: 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68  he custom VFS sh
aa00: 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65  ould abandon the
aa10: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72  .** current oper
aa20: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
aa30: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
aa40: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a  TEMPFILENAME]].*
aa50: 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63  * ^Application c
aa60: 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53  an invoke the [S
aa70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
aa80: 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63  FILENAME] file-c
aa90: 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76  ontrol.** to hav
aaa0: 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74  e SQLite generat
aab0: 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  e a.** temporary
aac0: 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20   filename using 
aad0: 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
aae0: 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f  hm that is follo
aaf0: 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a  wed to generate.
ab00: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
ab10: 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20  enames for TEMP 
ab20: 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72  tables and other
ab30: 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20   internal uses. 
ab40: 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   The.** argument
ab50: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61   should be a cha
ab60: 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62  r** which will b
ab70: 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  e filled with th
ab80: 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72  e filename.** wr
ab90: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
aba0: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
abb0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
abc0: 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20  )].  The caller 
abd0: 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65  should.** invoke
abe0: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
abf0: 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20  ] on the result 
ac00: 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72  to avoid a memor
ac10: 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  y leak..**.** <l
ac20: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
ac30: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  _MMAP_SIZE]].** 
ac40: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
ac50: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
ac60: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e control is use
ac70: 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65  d to query or se
ac80: 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d  t the.** maximum
ac90: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
aca0: 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73   that will be us
acb0: 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61  ed for memory-ma
acc0: 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65  pped I/O..** The
acd0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
ace0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75  ointer to a valu
acf0: 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65  e of type sqlite
ad00: 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20  3_int64 that.** 
ad10: 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d  is an advisory m
ad20: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
ad30: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
ad40: 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70  le to memory map
ad50: 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  .  The.** pointe
ad60: 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  r is overwritten
ad70: 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61   with the old va
ad80: 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20  lue.  The limit 
ad90: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69  is not changed i
ada0: 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f  f.** the value o
adb0: 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65  riginally pointe
adc0: 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65  d to is negative
add0: 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72  , and so the cur
ade0: 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63  rent limit .** c
adf0: 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79  an be queried by
ae00: 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f   passing in a po
ae10: 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74  inter to a negat
ae20: 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69  ive number.  Thi
ae30: 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  s.** file-contro
ae40: 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  l is used intern
ae50: 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  ally to implemen
ae60: 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  t [PRAGMA mmap_s
ae70: 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ize]..**.** <li>
ae80: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
ae90: 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  RACE]].** The [S
aea0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43  QLITE_FCNTL_TRAC
aeb0: 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  E] file control 
aec0: 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72  provides advisor
aed0: 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  y information.**
aee0: 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75   to the VFS abou
aef0: 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65  t what the highe
af00: 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20  r layers of the 
af10: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65  SQLite stack are
af20: 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20   doing..** This 
af30: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
af40: 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53  used by some VFS
af50: 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e   activity tracin
af60: 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68  g [shims]..** Th
af70: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
af80: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
af90: 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20  string.  Higher 
afa0: 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a  layers in the.**
afb0: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61   SQLite stack ma
afc0: 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61  y generate insta
afd0: 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c  nces of this fil
afe0: 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20  e control if.** 
aff0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
b000: 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d  FCNTL_TRACE] com
b010: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
b020: 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
b030: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </ul>.*/.#def
b040: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b050: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
b060: 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
b070: 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f  ne SQLITE_GET_LO
b080: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
b090: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
b0a0: 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43  e SQLITE_SET_LOC
b0b0: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
b0c0: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
b0d0: 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52   SQLITE_LAST_ERR
b0e0: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NO              
b0f0: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
b100: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
b110: 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20  E_HINT          
b120: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
b130: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
b140: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  K_SIZE          
b150: 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
b160: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
b170: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
b180: 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
b190: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
b1a0: 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20  MITTED          
b1b0: 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
b1c0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
b1d0: 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20  V_RETRY         
b1e0: 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
b1f0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
b200: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31  WAL            1
b210: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
b220: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
b230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31                11
b240: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b250: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20  FCNTL_VFSNAME   
b260: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a               12.
b270: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b280: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
b290: 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23  VERWRITE    13.#
b2a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b2b0: 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20  NTL_PRAGMA      
b2c0: 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64             14.#d
b2d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b2e0: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20  TL_BUSYHANDLER  
b2f0: 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65            15.#de
b300: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b310: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20  L_TEMPFILENAME  
b320: 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66           16.#def
b330: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b340: 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20  _MMAP_SIZE      
b350: 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69          18.#defi
b360: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b370: 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20  TRACE           
b380: 20 20 20 20 20 20 20 31 39 0a 0a 2f 2a 0a 2a 2a         19../*.**
b390: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
b3a0: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68   Handle.**.** Th
b3b0: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
b3c0: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
b3d0: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
b3e0: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
b3f0: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
b400: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
b410: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
b420: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
b430: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
b440: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
b450: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
b460: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
b470: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
b480: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
b490: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
b4a0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
b4b0: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
b4c0: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
b4d0: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
b4e0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
b4f0: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
b500: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
b510: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
b520: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62   OS Interface Ob
b530: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ject.**.** An in
b540: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71  stance of the sq
b550: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
b560: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
b570: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a  erface between.*
b580: 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * the SQLite cor
b590: 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c  e and the underl
b5a0: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
b5b0: 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73  ystem.  The "vfs
b5c0: 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65  ".** in the name
b5d0: 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73   of the object s
b5e0: 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75  tands for "virtu
b5f0: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e  al file system".
b600: 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46    See.** the [VF
b610: 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74  S | VFS document
b620: 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68  ation] for furth
b630: 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  er information..
b640: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
b650: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
b660: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
b670: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
b680: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
b690: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
b6a0: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
b6b0: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
b6c0: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
b6d0: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
b6e0: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
b6f0: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
b700: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
b710: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
b720: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
b730: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
b740: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
b750: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
b760: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
b770: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
b780: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
b790: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
b7a0: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
b7b0: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
b7c0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
b7d0: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
b7e0: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
b7f0: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
b800: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
b810: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
b820: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
b830: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
b840: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
b850: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
b860: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
b870: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
b880: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
b890: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
b8a0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
b8b0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
b8c0: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
b8d0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
b8e0: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
b8f0: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
b900: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
b910: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
b920: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
b930: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
b940: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
b950: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
b960: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
b970: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
b980: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
b990: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
b9a0: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
b9b0: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
b9c0: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
b9d0: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
b9e0: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
b9f0: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
ba00: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
ba10: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
ba20: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
ba30: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
ba40: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
ba50: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
ba60: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
ba70: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
ba80: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
ba90: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
baa0: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
bab0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
bac0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
bad0: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
bae0: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
baf0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
bb00: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
bb10: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
bb20: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
bb30: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
bb40: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
bb50: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
bb60: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
bb70: 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c  .xOpen]].** ^SQL
bb80: 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
bb90: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
bba0: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
bbb0: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65  Open.** is eithe
bbc0: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
bbd0: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69   or string obtai
bbe0: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c  ned.** from xFul
bbf0: 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68  lPathname() with
bc00: 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66   an optional suf
bc10: 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49  fix added..** ^I
bc20: 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64  f a suffix is ad
bc30: 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65  ded to the zFile
bc40: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20  name parameter, 
bc50: 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69  it will.** consi
bc60: 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22  st of a single "
bc70: 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c  -" character fol
bc80: 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65  lowed by no more
bc90: 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68   than.** 11 alph
bca0: 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20  anumeric and/or 
bcb0: 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a  "-" characters..
bcc0: 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68  ** ^SQLite furth
bcd0: 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  er guarantees th
bce0: 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  at.** the string
bcf0: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
bd00: 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74  nd unchanged unt
bd10: 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a  il xClose() is.*
bd20: 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73  * called. Becaus
bd30: 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75  e of the previou
bd40: 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74  s sentence,.** t
bd50: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
bd60: 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f  ] can safely sto
bd70: 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  re a pointer to 
bd80: 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  the.** filename 
bd90: 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72  if it needs to r
bda0: 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65  emember the file
bdb0: 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65  name for some re
bdc0: 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ason..** If the 
bdd0: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
bde0: 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20  ter to xOpen is 
bdf0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
be00: 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73  hen xOpen.** mus
be10: 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e  t invent its own
be20: 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20   temporary name 
be30: 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e  for the file.  ^
be40: 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a  Whenever the .**
be50: 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   xFilename param
be60: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20  eter is NULL it 
be70: 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65  will also be the
be80: 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a   case that the.*
be90: 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  * flags paramete
bea0: 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b  r will include [
beb0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
bec0: 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a  TEONCLOSE]..**.*
bed0: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
bee0: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20  ment to xOpen() 
bef0: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74  includes all bit
bf00: 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20  s set in.** the 
bf10: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
bf20: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
bf30: 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73  v2()].  Or if [s
bf40: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
bf50: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
bf60: 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  en16()] is used,
bf70: 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c   then flags incl
bf80: 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a  udes at least.**
bf90: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
bfa0: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
bfb0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
bfc0: 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20   .** If xOpen() 
bfd0: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
bfe0: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
bff0: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
c000: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51  o.** include [SQ
c010: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
c020: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73  LY].  Other bits
c030: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d   in *pOutFlags m
c040: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ay be set..**.**
c050: 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61   ^(SQLite will a
c060: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
c070: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
c080: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28  gs to the xOpen(
c090: 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e  ).** call, depen
c0a0: 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65  ding on the obje
c0b0: 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a  ct being opened:
c0c0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
c0d0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
c0e0: 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_MAIN_DB].** <l
c0f0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
c100: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _MAIN_JOURNAL].*
c110: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
c120: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a  OPEN_TEMP_DB].**
c130: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
c140: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
c150: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
c160: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
c170: 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  T_DB].** <li>  [
c180: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
c190: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
c1a0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
c1b0: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  STER_JOURNAL].**
c1c0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
c1d0: 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  PEN_WAL].** </ul
c1e0: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  >)^.**.** The fi
c1f0: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74  le I/O implement
c200: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68  ation can use th
c210: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c  e object type fl
c220: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65  ags to.** change
c230: 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c   the way it deal
c240: 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46  s with files.  F
c250: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  or example, an a
c260: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68  pplication.** th
c270: 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  at does not care
c280: 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63   about crash rec
c290: 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63  overy or rollbac
c2a0: 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20  k might make.** 
c2b0: 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f  the open of a jo
c2c0: 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d  urnal file a no-
c2d0: 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74  op.  Writes to t
c2e0: 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  his journal woul
c2f0: 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d  d.** also be no-
c300: 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74  ops, and any att
c310: 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65  empt to read the
c320: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72   journal would r
c330: 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f  eturn.** SQLITE_
c340: 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69  IOERR.  Or the i
c350: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
c360: 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68  ght recognize th
c370: 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  at a database.**
c380: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f   file will be do
c390: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
c3a0: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
c3b0: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
c3c0: 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  ndom.** order an
c3d0: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
c3e0: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
c3f0: 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51  dingly..**.** SQ
c400: 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  Lite might also 
c410: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
c420: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
c430: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
c440: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
c450: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
c460: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
c470: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
c480: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
c490: 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  E].** </ul>.**.*
c4a0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  * The [SQLITE_OP
c4b0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
c4c0: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
c4d0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a   file should be.
c4e0: 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ** deleted when 
c4f0: 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e  it is closed.  ^
c500: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
c510: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
c520: 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66  ** will be set f
c530: 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65  or TEMP database
c540: 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72  s and their jour
c550: 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a  nals, transient.
c560: 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e  ** databases, an
c570: 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a  d subjournals..*
c580: 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
c590: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
c5a0: 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73  ] flag is always
c5b0: 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63   used in conjunc
c5c0: 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65  tion.** with the
c5d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
c5e0: 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63  EATE] flag, whic
c5f0: 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63  h are both direc
c600: 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73  tly.** analogous
c610: 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61   to the O_EXCL a
c620: 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73  nd O_CREAT flags
c630: 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70   of the POSIX op
c640: 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68  en().** API.  Th
c650: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58  e SQLITE_OPEN_EX
c660: 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68  CLUSIVE flag, wh
c670: 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74  en paired with t
c680: 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50  he .** SQLITE_OP
c690: 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73  EN_CREATE, is us
c6a0: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
c6b0: 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  hat file should 
c6c0: 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65  always.** be cre
c6d0: 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69  ated, and that i
c6e0: 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66  t is an error if
c6f0: 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73   it already exis
c700: 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e  ts..** It is <i>
c710: 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20  not</i> used to 
c720: 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c  indicate the fil
c730: 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e  e should be open
c740: 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75  ed .** for exclu
c750: 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a  sive access..**.
c760: 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f  ** ^At least szO
c770: 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d  sFile bytes of m
c780: 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61  emory are alloca
c790: 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  ted by SQLite.**
c7a0: 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73   to hold the  [s
c7b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72  qlite3_file] str
c7c0: 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73  ucture passed as
c7d0: 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72   the third.** ar
c7e0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e  gument to xOpen.
c7f0: 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68    The xOpen meth
c800: 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  od does not have
c810: 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20   to.** allocate 
c820: 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69  the structure; i
c830: 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69  t should just fi
c840: 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20  ll it in.  Note 
c850: 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65  that.** the xOpe
c860: 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65  n method must se
c870: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
c880: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65  le.pMethods to e
c890: 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64  ither.** a valid
c8a0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
c8b0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20  hods] object or 
c8c0: 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20  to NULL.  xOpen 
c8d0: 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20  must do.** this 
c8e0: 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e  even if the open
c8f0: 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20   fails.  SQLite 
c900: 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65  expects that the
c910: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
c920: 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e  ethods.** elemen
c930: 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  t will be valid 
c940: 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75  after xOpen retu
c950: 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f  rns regardless o
c960: 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a  f the success.**
c970: 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74   or failure of t
c980: 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a  he xOpen call..*
c990: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
c9a0: 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20  fs.xAccess]].** 
c9b0: 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d  ^The flags argum
c9c0: 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29  ent to xAccess()
c9d0: 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f   may be [SQLITE_
c9e0: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a  ACCESS_EXISTS].*
c9f0: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  * to test for th
ca00: 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61  e existence of a
ca10: 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54   file, or [SQLIT
ca20: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
ca30: 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77  TE] to.** test w
ca40: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
ca50: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
ca60: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
ca70: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
ca80: 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68  ** to test wheth
ca90: 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  er a file is at 
caa0: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
cab0: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
cac0: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
cad0: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
cae0: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
caf0: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
cb00: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
cb10: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70   for the.** outp
cb20: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50  ut buffer xFullP
cb30: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78  athname.  The ex
cb40: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
cb50: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
cb60: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
cb70: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
cb80: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
cb90: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
cba0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20  uffer.** is not 
cbb0: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53  large enough, [S
cbc0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
cbd0: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
cbe0: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69  ed. Since this i
cbf0: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20  s.** handled as 
cc00: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
cc10: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70   SQLite, vfs imp
cc20: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
cc30: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20  uld endeavor.** 
cc40: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
cc50: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74  by setting mxPat
cc60: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
cc70: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
cc80: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  lue..**.** The x
cc90: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53  Randomness(), xS
cca0: 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74  leep(), xCurrent
ccb0: 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72  Time(), and xCur
ccc0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a  rentTimeInt64().
ccd0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ** interfaces ar
cce0: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
ccf0: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
cd00: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
cd10: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
cd20: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
cd30: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
cd40: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
cd50: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
cd60: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
cd70: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
cd80: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
cd90: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
cda0: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
cdb0: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
cdc0: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
cdd0: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
cde0: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
cdf0: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68   obtained..** Th
ce00: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
ce10: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
ce20: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
ce30: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
ce40: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
ce50: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
ce60: 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75  given.  ^The xCu
ce70: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d  rrentTime().** m
ce80: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
ce90: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65  Julian Day Numbe
cea0: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r for the curren
ceb0: 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  t date and time 
cec0: 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67  as.** a floating
ced0: 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a   point value..**
cee0: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
cef0: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
cf00: 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20   returns, as an 
cf10: 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c  integer, the Jul
cf20: 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65  ian.** Day Numbe
cf30: 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20  r multiplied by 
cf40: 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75  86400000 (the nu
cf50: 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
cf60: 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34  onds in .** a 24
cf70: 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a  -hour day).  .**
cf80: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
cf90: 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69  e the xCurrentTi
cfa0: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
cfb0: 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72   to get the curr
cfc0: 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20  ent.** date and 
cfd0: 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74  time if that met
cfe0: 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65  hod is available
cff0: 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73   (if iVersion is
d000: 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65   2 or .** greate
d010: 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69  r and the functi
d020: 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
d030: 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c  t NULL) and will
d040: 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f   fall back.** to
d050: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20   xCurrentTime() 
d060: 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  if xCurrentTimeI
d070: 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69  nt64() is unavai
d080: 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lable..**.** ^Th
d090: 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  e xSetSystemCall
d0a0: 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61  (), xGetSystemCa
d0b0: 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53  ll(), and xNestS
d0c0: 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65  ystemCall() inte
d0d0: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
d0e0: 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51  t used by the SQ
d0f0: 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73  Lite core.  Thes
d100: 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72  e optional inter
d110: 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64  faces are provid
d120: 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46  ed.** by some VF
d130: 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74  Ses to facilitat
d140: 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65  e testing of the
d150: 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76   VFS code. By ov
d160: 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73  erriding .** sys
d170: 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66  tem calls with f
d180: 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69  unctions under i
d190: 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65  ts control, a te
d1a0: 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a  st program can.*
d1b0: 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74  * simulate fault
d1c0: 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64  s and error cond
d1d0: 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c  itions that woul
d1e0: 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64  d otherwise be d
d1f0: 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69  ifficult.** or i
d200: 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64  mpossible to ind
d210: 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66  uce.  The set of
d220: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68   system calls th
d230: 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  at can be overri
d240: 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66  dden.** varies f
d250: 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61  rom one VFS to a
d260: 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d  nother, and from
d270: 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20   one version of 
d280: 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20  the same VFS to 
d290: 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70  the.** next.  Ap
d2a0: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
d2b0: 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66  use these interf
d2c0: 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65  aces must be pre
d2d0: 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a  pared for any.**
d2e0: 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65   or all of these
d2f0: 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62   interfaces to b
d300: 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68  e NULL or for th
d310: 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20  eir behavior to 
d320: 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f  change.** from o
d330: 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68  ne release to th
d340: 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  e next.  Applica
d350: 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61  tions must not a
d360: 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73  ttempt to access
d370: 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65  .** any of these
d380: 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20   methods if the 
d390: 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20  iVersion of the 
d3a0: 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e  VFS is less than
d3b0: 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73   3..*/.typedef s
d3c0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
d3d0: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74  s sqlite3_vfs;.t
d3e0: 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
d3f0: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
d400: 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74  r)(void);.struct
d410: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20   sqlite3_vfs {. 
d420: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20   int iVersion;  
d430: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
d440: 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e  ucture version n
d450: 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79  umber (currently
d460: 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f   3) */.  int szO
d470: 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20  sFile;          
d480: 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62    /* Size of sub
d490: 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f  classed sqlite3_
d4a0: 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78  file */.  int mx
d4b0: 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20  Pathname;       
d4c0: 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69     /* Maximum fi
d4d0: 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67  le pathname leng
d4e0: 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  th */.  sqlite3_
d4f0: 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20  vfs *pNext;     
d500: 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65   /* Next registe
d510: 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e  red VFS */.  con
d520: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20  st char *zName; 
d530: 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
d540: 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69   this virtual fi
d550: 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76  le system */.  v
d560: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
d570: 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74          /* Point
d580: 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
d590: 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20  n-specific data 
d5a0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  */.  int (*xOpen
d5b0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d5c0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
d5d0: 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e, sqlite3_file*
d5e0: 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
d5f0: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
d600: 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69  *pOutFlags);.  i
d610: 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71  nt (*xDelete)(sq
d620: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
d630: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
d640: 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69  nt syncDir);.  i
d650: 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71  nt (*xAccess)(sq
d660: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
d670: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
d680: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
d690: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
d6a0: 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28  *xFullPathname)(
d6b0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
d6c0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
d6d0: 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20   int nOut, char 
d6e0: 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a  *zOut);.  void *
d6f0: 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74  (*xDlOpen)(sqlit
d700: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
d710: 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b  har *zFilename);
d720: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72  .  void (*xDlErr
d730: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
d740: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
d750: 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76  r *zErrMsg);.  v
d760: 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28  oid (*(*xDlSym)(
d770: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69  sqlite3_vfs*,voi
d780: 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  d*, const char *
d790: 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b  zSymbol))(void);
d7a0: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f  .  void (*xDlClo
d7b0: 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
d7c0: 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20  , void*);.  int 
d7d0: 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73  (*xRandomness)(s
d7e0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
d7f0: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f   nByte, char *zO
d800: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c  ut);.  int (*xSl
d810: 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73  eep)(sqlite3_vfs
d820: 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f  *, int microseco
d830: 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  nds);.  int (*xC
d840: 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69  urrentTime)(sqli
d850: 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65  te3_vfs*, double
d860: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74  *);.  int (*xGet
d870: 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74  LastError)(sqlit
d880: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68  e3_vfs*, int, ch
d890: 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  ar *);.  /*.  **
d8a0: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
d8b0: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
d8c0: 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74  n 1 of the sqlit
d8d0: 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a  e_vfs object.  *
d8e0: 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  * definition.  T
d8f0: 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77  hose that follow
d900: 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65   are added in ve
d910: 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72  rsion 2 or later
d920: 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43  .  */.  int (*xC
d930: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29  urrentTimeInt64)
d940: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73  (sqlite3_vfs*, s
d950: 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a  qlite3_int64*);.
d960: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
d970: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
d980: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e  in versions 1 an
d990: 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74  d 2 of the sqlit
d9a0: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
d9b0: 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61  ** Those below a
d9c0: 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  re for version 3
d9d0: 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20   and greater..  
d9e0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53  */.  int (*xSetS
d9f0: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
da00: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
da10: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
da20: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
da30: 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63  ;.  sqlite3_sysc
da40: 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79  all_ptr (*xGetSy
da50: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
da60: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
da70: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f  ar *zName);.  co
da80: 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78  nst char *(*xNex
da90: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
daa0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
dab0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20   char *zName);. 
dac0: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
dad0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
dae0: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72  n versions 1 thr
daf0: 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71  ough 3 of the sq
db00: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
db10: 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73  .  ** New fields
db20: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
db30: 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69   in figure versi
db40: 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69  ons.  The iVersi
db50: 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69  on.  ** value wi
db60: 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65  ll increment whe
db70: 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65  never this happe
db80: 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  ns. .  */.};../*
db90: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
dba0: 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63  ags for the xAcc
dbb0: 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ess VFS method.*
dbc0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
dbd0: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e  er constants can
dbe0: 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20   be used as the 
dbf0: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
dc00: 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73  to.** the xAcces
dc10: 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b  s method of an [
dc20: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
dc30: 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72  ect.  They deter
dc40: 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e  mine.** what kin
dc50: 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73  d of permissions
dc60: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
dc70: 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66  hod is looking f
dc80: 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  or..** With SQLI
dc90: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
dca0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
dcb0: 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63  thod.** simply c
dcc0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
dcd0: 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a  e file exists..*
dce0: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
dcf0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20  CESS_READWRITE, 
dd00: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
dd10: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
dd20: 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64  ther the named d
dd30: 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68  irectory is both
dd40: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
dd50: 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74  itable.** (in ot
dd60: 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69  her words, if fi
dd70: 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64  les can be added
dd80: 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72  , removed, and r
dd90: 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a  enamed within.**
dda0: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e   the directory).
ddb0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41  .** The SQLITE_A
ddc0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
ddd0: 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72  constant is curr
dde0: 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20  ently used only 
ddf0: 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f  by the.** [temp_
de00: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
de10: 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20  pragma], though 
de20: 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67  this could chang
de30: 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a  e in a future.**
de40: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
de50: 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  te..** With SQLI
de60: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20  TE_ACCESS_READ, 
de70: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
de80: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
de90: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73  ther the file is
dea0: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
deb0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
dec0: 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a  AD constant is.*
ded0: 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73  * currently unus
dee0: 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69  ed, though it mi
def0: 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61  ght be used in a
df00: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
df10: 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f  of.** SQLite..*/
df20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
df30: 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
df40: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
df50: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
df60: 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62  TE 1   /* Used b
df70: 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74  y PRAGMA temp_st
df80: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f  ore_directory */
df90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dfa0: 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20  ACCESS_READ     
dfb0: 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a   2   /* Unused *
dfc0: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
dfd0: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
dfe0: 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65   xShmLock VFS me
dff0: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
e000: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
e010: 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61  ts define the va
e020: 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70  rious locking op
e030: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f  erations.** allo
e040: 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c  wed by the xShmL
e050: 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73  ock method of [s
e060: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
e070: 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c  s].  The.** foll
e080: 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e  owing are the on
e090: 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61  ly legal combina
e0a0: 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74  tions of flags t
e0b0: 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63  o the.** xShmLoc
e0c0: 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  k method:.**.** 
e0d0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  <ul>.** <li>  SQ
e0e0: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
e0f0: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
e100: 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
e110: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
e120: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
e130: 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  E.** <li>  SQLIT
e140: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
e150: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
e160: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
e170: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
e180: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
e190: 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VE.** </ul>.**.*
e1a0: 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67  * When unlocking
e1b0: 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45  , the same SHARE
e1c0: 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66  D or EXCLUSIVE f
e1d0: 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70  lag must be supp
e1e0: 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67  lied as.** was g
e1f0: 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72  iven no the corr
e200: 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20  esponding lock. 
e210: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d   .**.** The xShm
e220: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20  Lock method can 
e230: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
e240: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
e250: 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74  SHARED or.** bet
e260: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
e270: 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74  d EXCLUSIVE.  It
e280: 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69   cannot transiti
e290: 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45  on between SHARE
e2a0: 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49  D.** and EXCLUSI
e2b0: 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  VE..*/.#define S
e2c0: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
e2d0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
e2e0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
e2f0: 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
e300: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48  ne SQLITE_SHM_SH
e310: 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65  ARED       4.#de
e320: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
e330: 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a  EXCLUSIVE    8..
e340: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
e350: 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b  Maximum xShmLock
e360: 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65   index.**.** The
e370: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
e380: 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   on [sqlite3_io_
e390: 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65  methods] may use
e3a0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
e3b0: 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70  en 0 and this up
e3c0: 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73  per bound as its
e3d0: 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65   "offset" argume
e3e0: 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  nt..** The SQLit
e3f0: 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65  e core will neve
e400: 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71  r attempt to acq
e410: 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20  uire or release 
e420: 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64  a.** lock outsid
e430: 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a  e of this range.
e440: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
e450: 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20  E_SHM_NLOCK     
e460: 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     8.../*.** CAP
e470: 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a  I3REF: Initializ
e480: 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  e The SQLite Lib
e490: 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rary.**.** ^The 
e4a0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e4b0: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69  ze() routine ini
e4c0: 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20  tializes the.** 
e4d0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
e4e0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68   ^The sqlite3_sh
e4f0: 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65  utdown() routine
e500: 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  .** deallocates 
e510: 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68  any resources th
e520: 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65  at were allocate
e530: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  d by sqlite3_ini
e540: 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68  tialize()..** Th
e550: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
e560: 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64   designed to aid
e570: 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74   in process init
e580: 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a  ialization and.*
e590: 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d  * shutdown on em
e5a0: 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20  bedded systems. 
e5b0: 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70   Workstation app
e5c0: 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a  lications using.
e5d0: 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c  ** SQLite normal
e5e0: 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ly do not need t
e5f0: 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  o invoke either 
e600: 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
e610: 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  s..**.** A call 
e620: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
e630: 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65  alize() is an "e
e640: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
e650: 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66  f it is.** the f
e660: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
e670: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
e680: 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67  s invoked during
e690: 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66   the lifetime of
e6a0: 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c  .** the process,
e6b0: 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65   or if it is the
e6c0: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
e6d0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
e6e0: 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66   is invoked.** f
e6f0: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20  ollowing a call 
e700: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
e710: 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61  own().  ^(Only a
e720: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
e730: 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69  .** of sqlite3_i
e740: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73  nitialize() does
e750: 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74   any initializat
e760: 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ion.  All other 
e770: 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72  calls.** are har
e780: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
e790: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
e7a0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
e7b0: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
e7c0: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
e7d0: 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
e7e0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
e7f0: 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65  shutdown() since
e800: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
e810: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20  3_initialize(). 
e820: 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66   ^(Only.** an ef
e830: 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20  fective call to 
e840: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
e850: 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e  () does any dein
e860: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  itialization..**
e870: 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64   All other valid
e880: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
e890: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65  3_shutdown() are
e8a0: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
e8b0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  .)^.**.** The sq
e8c0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
e8d0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
e8e0: 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20  threadsafe, but 
e8f0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
e900: 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54  ().** is not.  T
e910: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
e920: 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  own() interface 
e930: 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c  must only be cal
e940: 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69  led from a.** si
e950: 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c  ngle thread.  Al
e960: 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  l open [database
e970: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75   connections] mu
e980: 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64  st be closed and
e990: 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51   all.** other SQ
e9a0: 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d  Lite resources m
e9b0: 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  ust be deallocat
e9c0: 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f  ed prior to invo
e9d0: 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  king.** sqlite3_
e9e0: 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a  shutdown()..**.*
e9f0: 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68  * Among other th
ea00: 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69  ings, ^sqlite3_i
ea10: 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c  nitialize() will
ea20: 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
ea30: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53  e3_os_init().  S
ea40: 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74  imilarly, ^sqlit
ea50: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
ea60: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c   will invoke sql
ea70: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a  ite3_os_end()..*
ea80: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
ea90: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
eaa0: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
eab0: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
eac0: 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f  ccess..** ^If fo
ead0: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73  r some reason, s
eae0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
eaf0: 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  e() is unable to
eb00: 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74   initialize.** t
eb10: 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68  he library (perh
eb20: 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65  aps it is unable
eb30: 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e   to allocate a n
eb40: 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73  eeded resource s
eb50: 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65  uch.** as a mute
eb60: 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e  x) it returns an
eb70: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74   [error code] ot
eb80: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
eb90: 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _OK]..**.** ^The
eba0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ebb0: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ize() routine is
ebc0: 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c   called internal
ebd0: 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72  ly by many other
ebe0: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
ebf0: 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e  faces so that an
ec00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75   application usu
ec10: 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65  ally does not ne
ec20: 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
ec30: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ec40: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  ze() directly.  
ec50: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71  For example, [sq
ec60: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
ec70: 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69   calls sqlite3_i
ec80: 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74  nitialize() so t
ec90: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
eca0: 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  y will be automa
ecb0: 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69  tically.** initi
ecc0: 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c  alized when [sql
ecd0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20  ite3_open()] is 
ece0: 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73  called if it has
ecf0: 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69   not be initiali
ed00: 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20  zed.** already. 
ed10: 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51   ^However, if SQ
ed20: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
ed30: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
ed40: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
ed50: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
ed60: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68   option, then th
ed70: 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c  e automatic call
ed80: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  s to sqlite3_ini
ed90: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65  tialize().** are
eda0: 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65   omitted and the
edb0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
edc0: 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69  t call sqlite3_i
edd0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
ede0: 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  ctly.** prior to
edf0: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
ee00: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
ee10: 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20  e.  For maximum 
ee20: 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20  portability,.** 
ee30: 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
ee40: 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
ee50: 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b  ons always invok
ee60: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
ee70: 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74  lize().** direct
ee80: 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ly prior to usin
ee90: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
eea0: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
eeb0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a  uture releases.*
eec0: 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  * of SQLite may 
eed0: 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49  require this.  I
eee0: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
eef0: 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69  he behavior exhi
ef00: 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51  bited.** when SQ
ef10: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
ef20: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d   with [SQLITE_OM
ef30: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67  IT_AUTOINIT] mig
ef40: 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a  ht become the.**
ef50: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
ef60: 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  r in some future
ef70: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
ef80: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te..**.** The sq
ef90: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
efa0: 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65  routine does ope
efb0: 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
efc0: 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61  ecific.** initia
efd0: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  lization of the 
efe0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
eff0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
f000: 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  end().** routine
f010: 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
f020: 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  ct of sqlite3_os
f030: 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61  _init().  Typica
f040: 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f  l tasks.** perfo
f050: 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f  rmed by these ro
f060: 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61  utines include a
f070: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61  llocation or dea
f080: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
f090: 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73  static resources
f0a0: 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  , initialization
f0b0: 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61   of global varia
f0c0: 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67  bles,.** setting
f0d0: 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73   up a default [s
f0e0: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75  qlite3_vfs] modu
f0f0: 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75  le, or setting u
f100: 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63  p.** a default c
f110: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69  onfiguration usi
f120: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ng [sqlite3_conf
f130: 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ig()]..**.** The
f140: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
f150: 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  uld never invoke
f160: 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
f170: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20  os_init().** or 
f180: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
f190: 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20   directly.  The 
f1a0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
f1b0: 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a  ld only invoke.*
f1c0: 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  * sqlite3_initia
f1d0: 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lize() and sqlit
f1e0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
f1f0: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
f200: 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  nit().** interfa
f210: 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74  ce is called aut
f220: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
f230: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f240: 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  () and.** sqlite
f250: 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61  3_os_end() is ca
f260: 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  lled by sqlite3_
f270: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70  shutdown().  App
f280: 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c  ropriate.** impl
f290: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20  ementations for 
f2a0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
f2b0: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
f2c0: 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75  _end().** are bu
f2d0: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20  ilt into SQLite 
f2e0: 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69  when it is compi
f2f0: 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69  led for Unix, Wi
f300: 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a  ndows, or OS/2..
f310: 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20  ** When [custom 
f320: 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66  builds | built f
f330: 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72  or other platfor
f340: 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68  ms].** (using th
f350: 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48  e [SQLITE_OS_OTH
f360: 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ER=1] compile-ti
f370: 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
f380: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
f390: 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
f3a0: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
f3b0: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
f3c0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
f3d0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
f3e0: 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
f3f0: 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
f400: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
f410: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
f420: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
f430: 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
f440: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
f450: 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
f460: 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72   some other [err
f470: 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a  or code] upon.**
f480: 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74   failure..*/.int
f490: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f4a0: 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  ize(void);.int s
f4b0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f4c0: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
f4d0: 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
f4e0: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
f4f0: 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
f500: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
f510: 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
f520: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
f530: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
f540: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
f550: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
f560: 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
f570: 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
f580: 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
f590: 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
f5a0: 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
f5b0: 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
f5c0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
f5d0: 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
f5e0: 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
f5f0: 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
f600: 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
f610: 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
f620: 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
f630: 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
f640: 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
f650: 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
f660: 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
f670: 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
f680: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  eds..**.** The s
f690: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
f6a0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
f6b0: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
f6c0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
f6d0: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
f6e0: 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
f6f0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
f700: 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
f710: 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
f720: 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
f730: 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  g() is running. 
f740: 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71   Furthermore, sq
f750: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a  lite3_config().*
f760: 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
f770: 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
f780: 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
f790: 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
f7a0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f7b0: 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
f7c0: 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
f7d0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
f7e0: 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
f7f0: 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c  config() is call
f800: 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
f810: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
f820: 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73  and before.** [s
f830: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f840: 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20  )] then it will 
f850: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49  return SQLITE_MI
f860: 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68  SUSE..** Note, h
f870: 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71  owever, that ^sq
f880: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63  lite3_config() c
f890: 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20  an be called as 
f8a0: 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69  part of the.** i
f8b0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
f8c0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
f8d0: 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33  defined [sqlite3
f8e0: 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a  _os_init()]..**.
f8f0: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
f900: 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
f910: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20  _config() is an 
f920: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66  integer.** [conf
f930: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
f940: 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
f950: 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
f960: 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
f970: 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
f980: 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
f990: 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
f9a0: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
f9b0: 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
f9c0: 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
f9d0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
f9e0: 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ..**.** ^When a 
f9f0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
fa00: 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
fa10: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
fa20: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
fa30: 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70  ]..** ^If the op
fa40: 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20  tion is unknown 
fa50: 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  or SQLite is una
fa60: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f  ble to set the o
fa70: 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68  ption.** then th
fa80: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
fa90: 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  ns a non-zero [e
faa0: 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69  rror code]..*/.i
fab0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  nt sqlite3_confi
fac0: 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  g(int, ...);../*
fad0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
fae0: 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65  nfigure database
faf0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a   connections.**.
fb00: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
fb10: 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
fb20: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
fb30: 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
fb40: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
fb50: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
fb60: 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
fb70: 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
fb80: 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
fb90: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
fba0: 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
fbb0: 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
fbc0: 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
fbd0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
fbe0: 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
fbf0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
fc00: 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  )..**.** The sec
fc10: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
fc20: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
fc30: 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
fc40: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42  he.** [SQLITE_DB
fc50: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
fc60: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
fc70: 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65   verb] - an inte
fc80: 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61  ger code .** tha
fc90: 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
fca0: 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
fcb0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
fcc0: 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
fcd0: 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62  nfigured..** Sub
fce0: 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
fcf0: 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  s vary depending
fd00: 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72   on the configur
fd10: 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a  ation verb..**.*
fd20: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
fd30: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
fd40: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
fd50: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
fd60: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
fd70: 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
fd80: 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sful..*/.int sql
fd90: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
fda0: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
fdb0: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
fdc0: 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
fdd0: 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
fde0: 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
fdf0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
fe00: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
fe10: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
fe20: 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
fe30: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
fe40: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
fe50: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
fe60: 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
fe70: 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
fe80: 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
fe90: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
fea0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
feb0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
fec0: 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
fed0: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
fee0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
fef0: 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
ff00: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
ff10: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
ff20: 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
ff30: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
ff40: 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
ff50: 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
ff60: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
ff70: 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
ff80: 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
ff90: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
ffa0: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
ffb0: 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
ffc0: 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
ffd0: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
ffe0: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
fff0: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
10000 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
10010 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
10020 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
10030 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
10040 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
10050 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
10060 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
10070 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
10080 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
10090 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
100a0 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
100b0 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
100c0 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
100d0 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
100e0 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
100f0 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
10100 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
10110 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
10120 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
10130 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
10140 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10150 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
10160 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
10170 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
10180 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
10190 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
101a0 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
101b0 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
101c0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
101d0 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
101e0 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
101f0 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
10200 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
10210 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
10220 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
10230 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
10240 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
10250 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52   The xMalloc, xR
10260 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65  ealloc, and xFre
10270 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  e methods must w
10280 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
10290 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f  malloc(), reallo
102a0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
102b0 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
102c0 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
102d0 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  rary..** ^SQLite
102e0 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
102f0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
10300 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
10310 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
10320 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
10330 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
10340 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a  o xRoundup..**.*
10350 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72  * xSize should r
10360 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61  eturn the alloca
10370 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65  ted size of a me
10380 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
10390 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
103a0 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c  tained from xMal
103b0 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e  loc or xRealloc.
103c0 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20    The allocated 
103d0 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79  size.** is alway
103e0 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69  s at least as bi
103f0 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74  g as the request
10400 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20  ed size but may 
10410 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a  be larger..**.**
10420 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65   The xRoundup me
10430 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61  thod returns wha
10440 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61  t would be the a
10450 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
10460 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  .** a memory all
10470 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20  ocation given a 
10480 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65  particular reque
10490 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74  sted size.  Most
104a0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
104b0 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d  ators round up m
104c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
104d0 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68  s at least to th
104e0 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a  e next multiple.
104f0 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61  ** of 8.  Some a
10500 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
10510 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d  up to a larger m
10520 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20  ultiple or to a 
10530 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45  power of 2..** E
10540 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
10550 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63  cation request c
10560 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68  oming in through
10570 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
10580 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
10590 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69  e3_realloc()] fi
105a0 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64  rst calls xRound
105b0 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70  up.  If xRoundup
105c0 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20   returns 0, .** 
105d0 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20  that causes the 
105e0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65  corresponding me
105f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10600 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54  to fail..**.** T
10610 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
10620 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
10630 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
10640 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .  (For example,
10650 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c  .** it might all
10660 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72  ocate any requir
10670 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69  e mutexes or ini
10680 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c  tialize internal
10690 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75   data.** structu
106a0 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64  res.  The xShutd
106b0 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  own method is in
106c0 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c  voked (indirectl
106d0 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  y) by.** [sqlite
106e0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e  3_shutdown()] an
106f0 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63  d should dealloc
10700 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65  ate any resource
10710 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79  s acquired.** by
10720 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70   xInit.  The pAp
10730 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73  pData pointer is
10740 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c   used as the onl
10750 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  y parameter to.*
10760 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75  * xInit and xShu
10770 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  tdown..**.** SQL
10780 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  ite holds the [S
10790 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
107a0 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78  IC_MASTER] mutex
107b0 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73   when it invokes
107c0 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65  .** the xInit me
107d0 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e  thod, so the xIn
107e0 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e  it method need n
107f0 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  ot be threadsafe
10800 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64  .  The.** xShutd
10810 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e  own method is on
10820 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b  ly called from [
10830 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10840 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a  ()] so it does.*
10850 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  * not need to be
10860 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68   threadsafe eith
10870 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68  er.  For all oth
10880 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69  er methods, SQLi
10890 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20  te.** holds the 
108a0 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
108b0 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20  ATIC_MEM] mutex 
108c0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a  as long as the.*
108d0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
108e0 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66  _MEMSTATUS] conf
108f0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10900 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77   is turned on (w
10910 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79  hich.** it is by
10920 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f   default) and so
10930 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65   the methods are
10940 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73   automatically s
10950 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f  erialized..** Ho
10960 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54  wever, if [SQLIT
10970 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
10980 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c  US] is disabled,
10990 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a   then the other.
109a0 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ** methods must 
109b0 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72  be threadsafe or
109c0 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72   else make their
109d0 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74   own arrangement
109e0 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69  s for.** seriali
109f0 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  zation..**.** SQ
10a00 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
10a10 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d  invoke xInit() m
10a20 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69  ore than once wi
10a30 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65  thout an interve
10a40 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  ning.** call to 
10a50 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a  xShutdown()..*/.
10a60 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
10a70 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
10a80 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ds sqlite3_mem_m
10a90 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
10aa0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
10ab0 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ds {.  void *(*x
10ac0 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20  Malloc)(int);   
10ad0 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20        /* Memory 
10ae0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74  allocation funct
10af0 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  ion */.  void (*
10b00 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20  xFree)(void*);  
10b10 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20          /* Free 
10b20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  a prior allocati
10b30 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a  on */.  void *(*
10b40 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c  xRealloc)(void*,
10b50 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65  int);  /* Resize
10b60 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
10b70 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29  /.  int (*xSize)
10b80 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
10b90 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65     /* Return the
10ba0 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f   size of an allo
10bb0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
10bc0 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29  (*xRoundup)(int)
10bd0 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f  ;          /* Ro
10be0 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73  und up request s
10bf0 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f  ize to allocatio
10c00 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20  n size */.  int 
10c10 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b  (*xInit)(void*);
10c20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e             /* In
10c30 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
10c40 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
10c50 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64  .  void (*xShutd
10c60 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  own)(void*);    
10c70 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a    /* Deinitializ
10c80 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
10c90 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
10ca0 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
10cb0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72             /* Ar
10cc0 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28  gument to xInit(
10cd0 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28  ) and xShutdown(
10ce0 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ) */.};../*.** C
10cf0 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
10d00 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
10d10 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e  * KEYWORDS: {con
10d20 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10d30 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  n}.**.** These c
10d40 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
10d50 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
10d60 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
10d70 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
10d80 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
10d90 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
10da0 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
10db0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
10dc0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
10dd0 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
10de0 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
10df0 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
10e00 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
10e10 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
10e20 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10e30 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
10e40 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
10e50 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
10e60 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
10e70 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
10e80 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
10e90 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
10ea0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
10eb0 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
10ec0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10ed0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
10ee0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
10ef0 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
10f00 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
10f10 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
10f20 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
10f30 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
10f40 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
10f50 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  l>.** [[SQLITE_C
10f60 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
10f70 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
10f80 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
10f90 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
10fa0 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
10fb0 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
10fc0 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
10fd0 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
10fe0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
10ff0 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] to Single-thre
11000 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
11010 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
11020 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67  .** all mutexing
11030 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65   and puts SQLite
11040 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65   into a mode whe
11050 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62  re it can only b
11060 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73  e used.** by a s
11070 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20  ingle thread.   
11080 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
11090 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
110a0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
110b0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
110c0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
110d0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
110e0 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
110f0 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  ot possible to c
11100 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61  hange the [threa
11110 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20  ding mode] from 
11120 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76  its default.** v
11130 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74  alue of Single-t
11140 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71  hread and so [sq
11150 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11160 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20  will return .** 
11170 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
11180 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
11190 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
111a0 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20  SINGLETHREAD.** 
111b0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
111c0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
111d0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
111e0 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c  _MULTITHREAD]] <
111f0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
11200 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74  _MULTITHREAD</dt
11210 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
11220 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
11230 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
11240 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
11250 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
11260 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75  ding mode] to Mu
11270 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  lti-thread.  In 
11280 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
11290 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
112a0 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
112b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
112c0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
112d0 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
112e0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
112f0 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
11300 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
11310 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
11320 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11330 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
11340 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
11350 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
11360 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
11370 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
11380 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
11390 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
113a0 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
113b0 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
113c0 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
113d0 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
113e0 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
113f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11400 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
11410 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74  time.  ^If SQLit
11420 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
11430 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
11440 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
11450 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11460 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
11470 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
11480 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
11490 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75  le to set the Mu
114a0 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
114b0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
114c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
114d0 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
114e0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
114f0 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
11500 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
11510 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
11520 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11530 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
11540 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
11550 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c  G_SERIALIZED]] <
11560 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
11570 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e  _SERIALIZED</dt>
11580 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
11590 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
115a0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
115b0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
115c0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
115d0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72  ing mode] to Ser
115e0 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65  ialized. In othe
115f0 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70  r words, this op
11600 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
11610 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
11620 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
11630 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
11640 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
11650 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
11660 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
11670 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
11680 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
11690 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
116a0 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
116b0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
116c0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
116d0 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
116e0 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
116f0 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
11700 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
11710 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11720 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
11730 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
11740 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
11750 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
11760 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
11770 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11780 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
11790 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
117a0 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
117b0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
117c0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
117d0 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
117e0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
117f0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
11800 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
11810 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
11820 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
11830 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
11840 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
11850 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69   to set the Seri
11860 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
11870 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
11880 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11890 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
118a0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
118b0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
118c0 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
118d0 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66  _SERIALIZED conf
118e0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
118f0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
11900 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
11910 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
11920 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f  _CONFIG_MALLOC</
11930 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
11940 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
11950 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
11960 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
11970 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
11980 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
11990 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
119a0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
119b0 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
119c0 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
119d0 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
119e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
119f0 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  n routines to be
11a00 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f   used in place o
11a10 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20  f.** the memory 
11a20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
11a30 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
11a40 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65  QLite.)^ ^SQLite
11a50 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77   makes.** its ow
11a60 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
11a70 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  f the content of
11a80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
11a90 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
11aa0 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74  ture.** before t
11ab0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
11ac0 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72  ig()] call retur
11ad0 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ns.</dd>.**.** [
11ae0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
11af0 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  ETMALLOC]] <dt>S
11b00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
11b10 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
11b20 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
11b30 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
11b40 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
11b50 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
11b60 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
11b70 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
11b80 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
11b90 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c  cture.  The [sql
11ba0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
11bb0 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
11bc0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
11bd0 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
11be0 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ned memory alloc
11bf0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29  ation routines.)
11c00 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
11c10 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
11c20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
11c30 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
11c40 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
11c50 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
11c60 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
11c70 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
11c80 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
11c90 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
11ca0 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
11cb0 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ple. </dd>.**.**
11cc0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
11cd0 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74  _MEMSTATUS]] <dt
11ce0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
11cf0 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a  EMSTATUS</dt>.**
11d00 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
11d10 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20  on takes single 
11d20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65  argument of type
11d30 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65   int, interprete
11d40 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65  d as a .** boole
11d50 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65  an, which enable
11d60 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
11d70 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20  e collection of 
11d80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11d90 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73  n .** statistics
11da0 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20  . ^(When memory 
11db0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
11dc0 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
11dd0 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c  ed, the .** foll
11de0 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74  owing SQLite int
11df0 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e  erfaces become n
11e00 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a  on-operational:.
11e10 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  **   <ul>.**   <
11e20 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
11e30 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20  ory_used()].**  
11e40 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
11e50 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
11e60 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
11e70 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
11e80 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20  limit64()].**   
11e90 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
11ea0 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75  atus()].**   </u
11eb0 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20  l>)^.** ^Memory 
11ec0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
11ed0 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65  stics are enable
11ee0 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c  d by default unl
11ef0 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  ess SQLite is.**
11f00 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
11f10 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d  SQLITE_DEFAULT_M
11f20 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77  EMSTATUS]=0 in w
11f30 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79  hich case memory
11f40 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  .** allocation s
11f50 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
11f60 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
11f70 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  t..** </dd>.**.*
11f80 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
11f90 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e  G_SCRATCH]] <dt>
11fa0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
11fb0 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RATCH</dt>.** <d
11fc0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
11fd0 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
11fe0 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
11ff0 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
12000 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61   use for.** scra
12010 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65  tch memory.  The
12020 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
12030 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74  uments:  A point
12040 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  er an 8-byte.** 
12050 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62  aligned memory b
12060 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68  uffer from which
12070 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c   the scratch all
12080 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65  ocations will be
12090 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73  .** drawn, the s
120a0 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61  ize of each scra
120b0 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28  tch allocation (
120c0 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20  sz),.** and the 
120d0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
120e0 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  f scratch alloca
120f0 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20  tions (N).  The 
12100 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d  sz.** argument m
12110 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c  ust be a multipl
12120 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20  e of 16..** The 
12130 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
12140 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72  ust be a pointer
12150 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c   to an 8-byte al
12160 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20  igned buffer.** 
12170 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
12180 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
12190 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
121a0 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68  l use no more th
121b0 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 62  an two scratch b
121c0 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61  uffers per threa
121d0 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75  d.  So.** N shou
121e0 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 69  ld be set to twi
121f0 63 65 20 74 68 65 20 65 78 70 65 63 74 65 64 20  ce the expected 
12200 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
12210 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53  f threads..** ^S
12220 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
12230 20 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74   require a scrat
12240 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69  ch buffer that i
12250 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a  s more than 6.**
12260 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62   times the datab
12270 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e  ase page size. ^
12280 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20  If SQLite needs 
12290 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c  needs additional
122a0 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
122b0 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ry beyond what i
122c0 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
122d0 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
122e0 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a   option, then .*
122f0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
12300 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65  c()] will be use
12310 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  d to obtain the 
12320 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f  memory needed.</
12330 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
12340 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
12350 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CHE]] <dt>SQLITE
12360 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
12370 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
12380 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
12390 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
123a0 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
123b0 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
123c0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61   for.** the data
123d0 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20  base page cache 
123e0 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74  with the default
123f0 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
12400 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a  ementation.  .**
12410 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   This configurat
12420 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  ion should not b
12430 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70  e used if an app
12440 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20  lication-define 
12450 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
12460 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
12470 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65  loaded using the
12480 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
12490 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a  CACHE2 option..*
124a0 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
124b0 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  e arguments to t
124c0 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f  his option: A po
124d0 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20  inter to 8-byte 
124e0 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72  aligned.** memor
124f0 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  y, the size of e
12500 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20  ach page buffer 
12510 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75  (sz), and the nu
12520 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e  mber of pages (N
12530 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67  )..** The sz arg
12540 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
12550 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
12560 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65  largest database
12570 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65   page.** (a powe
12580 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e  r of two between
12590 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20   512 and 32768) 
125a0 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78  plus a little ex
125b0 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  tra for each.** 
125c0 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54  page header.  ^T
125d0 68 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73  he page header s
125e0 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20  ize is 20 to 40 
125f0 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20  bytes depending 
12600 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61  on.** the host a
12610 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49  rchitecture.  ^I
12620 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61  t is harmless, a
12630 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61  part from the wa
12640 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  sted memory,.** 
12650 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74  to make sz a lit
12660 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20  tle too large.  
12670 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
12680 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69  ument should poi
12690 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74  nt to an allocat
126a0 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ion of at least 
126b0 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
126c0 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  mory..** ^SQLite
126d0 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65   will use the me
126e0 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79  mory provided by
126f0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
12700 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69  ent to satisfy i
12710 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65  ts.** memory nee
12720 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  ds for the first
12730 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74   N pages that it
12740 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20   adds to cache. 
12750 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a   ^If additional.
12760 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  ** page cache me
12770 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62  mory is needed b
12780 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
12790 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f  ovided by this o
127a0 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53  ption, then.** S
127b0 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73  QLite goes to [s
127c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
127d0 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f   for the additio
127e0 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63  nal storage spac
127f0 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  e..** The pointe
12800 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
12810 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20  rgument must.** 
12820 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
12830 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
12840 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
12850 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
12860 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64  e.** will be und
12870 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  efined.</dd>.**.
12880 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
12890 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51  IG_HEAP]] <dt>SQ
128a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
128b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
128c0 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
128d0 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
128e0 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
128f0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
12900 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  .** for all of i
12910 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
12920 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
12930 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ds beyond those 
12940 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20  provided.** for 
12950 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
12960 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b  G_SCRATCH] and [
12970 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
12980 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65  GECACHE]..** The
12990 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
129a0 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74  uments: An 8-byt
129b0 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65  e aligned pointe
129c0 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
129d0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
129e0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  f bytes in the m
129f0 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
12a00 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
12a10 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a  location size..*
12a20 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20  * ^If the first 
12a30 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
12a40 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20  ory pointer) is 
12a50 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74  NULL, then SQLit
12a60 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20  e reverts.** to 
12a70 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c  using its defaul
12a80 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
12a90 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d  or (the system m
12aa0 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
12ab0 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f  tation),.** undo
12ac0 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e  ing any prior in
12ad0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c  vocation of [SQL
12ae0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
12af0 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  C].  ^If the.** 
12b00 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
12b10 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65  s not NULL and e
12b20 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e  ither [SQLITE_EN
12b30 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72  ABLE_MEMSYS3] or
12b40 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
12b50 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20  LE_MEMSYS5] are 
12b60 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68  defined, then th
12b70 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
12b80 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
12b90 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
12ba0 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
12bb0 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
12bc0 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
12bd0 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
12be0 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
12bf0 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
12c00 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
12c10 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
12c20 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
12c30 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
12c40 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
12c50 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e  ined..** The min
12c60 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
12c70 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61  size is capped a
12c80 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61  t 2**12. Reasona
12c90 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f  ble values.** fo
12ca0 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  r the minimum al
12cb0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72  location size ar
12cc0 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32  e 2**5 through 2
12cd0 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  **8.</dd>.**.** 
12ce0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12cf0 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
12d00 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
12d10 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
12d20 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
12d30 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
12d40 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
12d50 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
12d60 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
12d70 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
12d80 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
12d90 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
12da0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
12db0 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
12dc0 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  el mutex routine
12dd0 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
12de0 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74  place.** the mut
12df0 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  ex routines buil
12e00 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
12e10 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20    ^SQLite makes 
12e20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
12e30 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
12e40 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
12e50 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
12e60 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c  e before the cal
12e70 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
12e80 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72  _config()] retur
12e90 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69  ns. ^If SQLite i
12ea0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
12eb0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
12ec0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
12ed0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
12ee0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
12ef0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
12f00 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
12f10 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
12f20 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
12f30 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
12f40 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
12f50 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
12f60 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
12f70 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69  NFIG_MUTEX confi
12f80 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
12f90 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
12fa0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
12fb0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
12fc0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
12fd0 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
12fe0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c  CONFIG_GETMUTEX<
12ff0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
13000 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
13010 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
13020 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
13030 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
13040 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
13050 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
13060 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
13070 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
13080 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
13090 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
130a0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
130b0 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
130c0 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
130d0 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
130e0 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
130f0 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
13100 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61   default mutex a
13110 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
13120 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
13130 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61  pper used to tra
13140 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66  ck mutex usage f
13150 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a  or performance.*
13160 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74  * profiling or t
13170 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d  esting, for exam
13180 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ple.   ^If SQLit
13190 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
131a0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
131b0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
131c0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
131d0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
131e0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
131f0 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
13200 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
13210 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
13220 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
13230 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
13240 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
13250 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
13260 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
13270 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13280 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
13290 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
132a0 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
132b0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
132c0 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e  LOOKASIDE]] <dt>
132d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
132e0 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
132f0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
13300 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
13310 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
13320 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c  rmine the defaul
13330 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t.** memory allo
13340 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c  cation for the l
13350 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
13360 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63  allocator on eac
13370 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
13380 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
13390 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
133a0 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
133b0 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
133c0 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64   buffer slot and
133d0 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74   the second is t
133e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
133f0 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20  slots allocated 
13400 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
13410 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20   connection.)^  
13420 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65  ^(This option se
13430 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66  ts the.** <i>def
13440 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69  ault</i> lookasi
13450 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51  de size. The [SQ
13460 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
13470 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62  OKASIDE].** verb
13480 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
13490 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
134a0 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
134b0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
134c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
134d0 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
134e0 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
134f0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13500 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
13510 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13520 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e  FIG_PCACHE2</dt>
13530 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
13540 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
13550 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
13560 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
13570 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69  r to.** an [sqli
13580 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
13590 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  ds2] object.  Th
135a0 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  is object specif
135b0 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ies the interfac
135c0 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d  e.** to a custom
135d0 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
135e0 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e  ementation.)^  ^
135f0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
13600 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62  opy of the.** ob
13610 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74  ject and uses it
13620 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20   for page cache 
13630 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13640 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ns.</dd>.**.** [
13650 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
13660 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  ETPCACHE2]] <dt>
13670 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13680 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  TPCACHE2</dt>.**
13690 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
136a0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
136b0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
136c0 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
136d0 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
136e0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
136f0 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74  ] object.  SQLit
13700 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20  e copies of the 
13710 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20  current.** page 
13720 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
13730 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f  tion into that o
13740 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  bject.)^ </dd>.*
13750 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13760 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53  NFIG_LOG]] <dt>S
13770 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
13780 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68  </dt>.** <dd> Th
13790 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
137a0 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  LOG option is us
137b0 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20  ed to configure 
137c0 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c  the SQLite.** gl
137d0 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d  obal [error log]
137e0 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54  ..** (^The SQLIT
137f0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
13800 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
13810 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74  guments: a point
13820 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74  er to a.** funct
13830 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20  ion with a call 
13840 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69  signature of voi
13850 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  d(*)(void*,int,c
13860 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a  onst char*), .**
13870 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74   and a pointer t
13880 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20  o void. ^If the 
13890 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
138a0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74   is not NULL, it
138b0 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62   is.** invoked b
138c0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  y [sqlite3_log()
138d0 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63  ] to process eac
138e0 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e  h logging event.
138f0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e    ^If the.** fun
13900 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
13910 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69   NULL, the [sqli
13920 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72  te3_log()] inter
13930 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e  face becomes a n
13940 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f  o-op..** ^The vo
13950 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  id pointer that 
13960 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  is the second ar
13970 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45  gument to SQLITE
13980 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a  _CONFIG_LOG is.*
13990 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  * passed through
139a0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61   as the first pa
139b0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
139c0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
139d0 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
139e0 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74  ction whenever t
139f0 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  hat function is 
13a00 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73  invoked.  ^The s
13a10 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
13a20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72  to.** the logger
13a30 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63   function is a c
13a40 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74  opy of the first
13a50 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
13a60 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  e corresponding.
13a70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  ** [sqlite3_log(
13a80 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69  )] call and is i
13a90 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20  ntended to be a 
13aa0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
13ab0 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   an.** [extended
13ac0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20   result code].  
13ad0 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
13ae0 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74  eter passed to t
13af0 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20  he logger is.** 
13b00 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65  log message afte
13b10 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61  r formatting via
13b20 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
13b30 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51  tf()]..** The SQ
13b40 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74  Lite logging int
13b50 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
13b60 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67  entrant; the log
13b70 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ger function.** 
13b80 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20  supplied by the 
13b90 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
13ba0 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20   not invoke any 
13bb0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
13bc0 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d  ..** In a multi-
13bd0 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61  threaded applica
13be0 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63  tion, the applic
13bf0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
13c00 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
13c10 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
13c20 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  afe. </dd>.**.**
13c30 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13c40 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _URI]] <dt>SQLIT
13c50 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20  E_CONFIG_URI.** 
13c60 3c 64 64 3e 5e 28 54 68 69 73 20 6f 70 74 69 6f  <dd>^(This optio
13c70 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
13c80 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
13c90 65 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65  e int. If non-ze
13ca0 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20  ro, then.** URI 
13cb0 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
13cc0 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66  ally enabled. If
13cd0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
13ce0 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49  s zero, then URI
13cf0 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20   handling.** is 
13d00 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
13d10 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e  d.)^ ^If URI han
13d20 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
13d30 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66  y enabled, all f
13d40 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73  ilenames.** pass
13d50 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ed to [sqlite3_o
13d60 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
13d70 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71  _open_v2()], [sq
13d80 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
13d90 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20  or.** specified 
13da0 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41  as part of [ATTA
13db0 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65  CH] commands are
13dc0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
13dd0 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73  URIs, regardless
13de0 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f  .** of whether o
13df0 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54  r not the [SQLIT
13e00 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
13e10 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
13e20 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
13e30 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
13e40 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f  d. ^If it is glo
13e50 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20  bally disabled, 
13e60 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  filenames are.**
13e70 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65   only interprete
13e80 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65  d as URIs if the
13e90 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
13ea0 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
13eb0 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  n the.** databas
13ec0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
13ed0 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66  opened. ^(By def
13ee0 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69  ault, URI handli
13ef0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
13f00 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20  * disabled. The 
13f10 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61  default value ma
13f20 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20  y be changed by 
13f30 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74  compiling with t
13f40 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53  he.** [SQLITE_US
13f50 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65  E_URI] symbol de
13f60 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  fined.)^.**.** [
13f70 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  [SQLITE_CONFIG_C
13f80 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
13f90 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AN]] <dt>SQLITE_
13fa0 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
13fb0 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64  INDEX_SCAN.** <d
13fc0 64 3e 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  d>^This option t
13fd0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e  akes a single in
13fe0 74 65 67 65 72 20 61 72 67 75 6d 65 6e 74 20 77  teger argument w
13ff0 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65  hich is interpre
14000 74 65 64 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c  ted as.** a bool
14010 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ean in order to 
14020 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
14030 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  e the use of cov
14040 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
14050 72 0a 2a 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20  r.** full table 
14060 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65  scans in the que
14070 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 20 20 5e  ry optimizer.  ^
14080 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
14090 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65  ing is determine
140a0 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c  d.** by the [SQL
140b0 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49  ITE_ALLOW_COVERI
140c0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63  NG_INDEX_SCAN] c
140d0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
140e0 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a  on, or is "on".*
140f0 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c  * if that compil
14100 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
14110 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65   omitted..** The
14120 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61   ability to disa
14130 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63  ble the use of c
14140 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
14150 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
14160 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75  cans.** is becau
14170 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63  se some incorrec
14180 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79  tly coded legacy
14190 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69   applications mi
141a0 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a  ght malfunction.
141b0 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69  ** when the opti
141c0 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  mization is enab
141d0 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20  led.  Providing 
141e0 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a  the ability to.*
141f0 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70  * disable the op
14200 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77  timization allow
14210 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67  s the older, bug
14220 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  gy application c
14230 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ode to work.** w
14240 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76  ithout change ev
14250 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65  en with newer ve
14260 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
14270 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
14280 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d  _CONFIG_PCACHE]]
14290 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
142a0 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20  _GETPCACHE]].** 
142b0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
142c0 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c  G_PCACHE and SQL
142d0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
142e0 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  ACHE.** <dd> The
142f0 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f  se options are o
14300 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75  bsolete and shou
14310 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62  ld not be used b
14320 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54  y new code..** T
14330 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64  hey are retained
14340 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
14350 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74  ompatibility but
14360 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e   are now no-ops.
14370 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
14380 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14390 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e  SQLLOG]].** <dt>
143a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
143b0 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  LLOG.** <dd>This
143c0 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
143d0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c  available if sql
143e0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
143f0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
14400 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f  ITE_ENABLE_SQLLO
14410 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  G] pre-processor
14420 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20   macro defined. 
14430 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
14440 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20  nt should.** be 
14450 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66  a pointer to a f
14460 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
14470 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
14480 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61  lite3*,const cha
14490 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65  r*, int)..** The
144a0 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62   second should b
144b0 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a  e of type (void*
144c0 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ). The callback 
144d0 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68  is invoked by th
144e0 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20  e library.** in 
144f0 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63  three separate c
14500 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64  ircumstances, id
14510 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
14520 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
14530 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
14540 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20  rameter. If the 
14550 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
14560 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20   is 0, then the 
14570 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14580 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73  ion.** passed as
14590 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
145a0 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65  ment has just be
145b0 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74  en opened. The t
145c0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
145d0 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66   points to a buf
145e0 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  fer containing t
145f0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d  he name of the m
14600 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
14610 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75  e. If the.** fou
14620 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
14630 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c   1, then the SQL
14640 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
14650 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
14660 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ter.** points to
14670 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65   has just been e
14680 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20  xecuted. Or, if 
14690 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
146a0 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a  eter is 2, then.
146b0 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ** the connectio
146c0 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61  n being passed a
146d0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
146e0 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20  ameter is being 
146f0 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74  closed. The.** t
14700 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
14710 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e  s passed NULL In
14720 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20   this case.  An 
14730 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67  example of using
14740 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75   this.** configu
14750 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61  ration option ca
14760 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65  n be seen in the
14770 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22   "test_sqllog.c"
14780 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a   source file in.
14790 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c  ** the canonical
147a0 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74   SQLite source t
147b0 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ree.</dd>.**.** 
147c0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
147d0 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  MMAP_SIZE]].** <
147e0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
147f0 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64  _MMAP_SIZE.** <d
14800 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d>^SQLITE_CONFIG
14810 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73  _MMAP_SIZE takes
14820 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65   two 64-bit inte
14830 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74  ger (sqlite3_int
14840 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  64) values.** th
14850 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75  at are the defau
14860 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  lt mmap size lim
14870 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20  it (the default 
14880 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b  setting for.** [
14890 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
148a0 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ]) and the maxim
148b0 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
148c0 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e  size limit..** ^
148d0 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
148e0 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72  ing can be overr
148f0 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61  idden by each da
14900 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14910 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65  n using.** eithe
14920 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d  r the [PRAGMA mm
14930 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64  ap_size] command
14940 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68  , or by using th
14950 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
14960 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
14970 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54  le control.  ^(T
14980 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
14990 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20  ed mmap size.** 
149a0 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  cannot be change
149b0 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 2e 20 20  d at run-time.  
149c0 4e 6f 72 20 6d 61 79 20 74 68 65 20 6d 61 78 69  Nor may the maxi
149d0 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70  mum allowed mmap
149e0 20 73 69 7a 65 0a 2a 2a 20 65 78 63 65 65 64 20   size.** exceed 
149f0 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
14a00 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69   maximum mmap si
14a10 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a  ze set by the.**
14a20 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41   [SQLITE_MAX_MMA
14a30 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d  P_SIZE] compile-
14a40 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a  time option.)^.*
14a50 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61 72 67  * ^If either arg
14a60 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70  ument to this op
14a70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65  tion is negative
14a80 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72 67 75  , then that argu
14a90 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67  ment is.** chang
14aa0 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c  ed to its compil
14ab0 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a  e-time default..
14ac0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
14ad0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14ae0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20  G_SINGLETHREAD  
14af0 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  1  /* nil */.#de
14b00 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14b10 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20  IG_MULTITHREAD  
14b20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   2  /* nil */.#d
14b30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14b40 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20  FIG_SERIALIZED  
14b50 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    3  /* nil */.#
14b60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14b70 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20  NFIG_MALLOC     
14b80 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
14b90 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
14ba0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14bb0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
14bc0 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
14bd0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
14be0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14bf0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
14c00 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69         6  /* voi
14c10 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
14c20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
14c30 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
14c40 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76  ACHE     7  /* v
14c50 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
14c60 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
14c70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
14c80 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a  P          8  /*
14c90 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74   void*, int nByt
14ca0 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64  e, int min */.#d
14cb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14cc0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20  FIG_MEMSTATUS   
14cd0 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20    9  /* boolean 
14ce0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14cf0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20  E_CONFIG_MUTEX  
14d00 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c        10  /* sql
14d10 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
14d20 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
14d30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14d40 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a  MUTEX     11  /*
14d50 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
14d60 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72  ethods* */./* pr
14d70 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f  eviously SQLITE_
14d80 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f  CONFIG_CHUNKALLO
14d90 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f  C 12 which is no
14da0 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64  w unused. */ .#d
14db0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14dc0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
14dd0 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20   13  /* int int 
14de0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14df0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
14e00 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d        14  /* no-
14e10 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
14e20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
14e30 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20  CACHE    15  /* 
14e40 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
14e50 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
14e60 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20  OG          16  
14e70 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20  /* xFunc, void* 
14e80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14e90 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20  E_CONFIG_URI    
14ea0 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74        17  /* int
14eb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14ec0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
14ed0 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71  2      18  /* sq
14ee0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
14ef0 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e  hods2* */.#defin
14f00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14f10 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20  GETPCACHE2   19 
14f20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
14f30 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
14f40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
14f50 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
14f60 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a  NDEX_SCAN 20  /*
14f70 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
14f80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
14f90 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f  LLOG       21  /
14fa0 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a  * xSqllog, void*
14fb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14fc0 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
14fd0 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71  IZE    22  /* sq
14fe0 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c  lite3_int64, sql
14ff0 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 0a 2f  ite3_int64 */../
15000 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
15010 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
15020 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  on Configuration
15030 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54   Options.**.** T
15040 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
15050 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
15060 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
15070 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
15080 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
15090 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
150a0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
150b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
150c0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
150d0 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
150e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
150f0 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
15100 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
15110 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
15120 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
15130 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
15140 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
15150 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
15160 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
15170 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
15180 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
15190 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
151a0 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
151b0 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
151c0 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71  orked.  ^The [sq
151d0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
151e0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
151f0 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
15200 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
15210 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
15220 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
15230 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
15240 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
15250 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
15260 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
15270 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
15280 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
15290 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
152a0 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74  akes three addit
152b0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20  ional arguments 
152c0 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
152d0 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64  he .** [lookasid
152e0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
152f0 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  or] configuratio
15300 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62  n for the [datab
15310 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
15320 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
15330 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69  rgument (the thi
15340 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
15350 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
15360 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f  ig()] is a.** po
15370 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
15380 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20  y buffer to use 
15390 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  for lookaside me
153a0 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  mory..** ^The fi
153b0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74  rst argument aft
153c0 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42  er the SQLITE_DB
153d0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
153e0 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20   verb.** may be 
153f0 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61  NULL in which ca
15400 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  se SQLite will a
15410 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c  llocate the.** l
15420 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
15430 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71  itself using [sq
15440 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
15450 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
15460 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
15470 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
15480 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
15490 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  ot.  ^The third 
154a0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
154b0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
154c0 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  ts.  The size of
154d0 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74   the buffer in t
154e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
154f0 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65  t must be greate
15500 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75  r than.** or equ
15510 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63  al to the produc
15520 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  t of the second 
15530 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65  and third argume
15540 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72  nts.  The buffer
15550 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67  .** must be alig
15560 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
15570 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20   boundary.  ^If 
15580 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
15590 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45  ent to.** SQLITE
155a0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
155b0 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c  IDE is not a mul
155c0 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69  tiple of 8, it i
155d0 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  s internally.** 
155e0 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20  rounded down to 
155f0 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72  the next smaller
15600 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20   multiple of 8. 
15610 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65   ^(The lookaside
15620 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69   memory.** confi
15630 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64  guration for a d
15640 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15650 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63  on can only be c
15660 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74  hanged when that
15670 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
15680 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
15690 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20  using lookaside 
156a0 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74  memory, or in ot
156b0 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65  her words.** whe
156c0 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76  n the "current v
156d0 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62  alue" returned b
156e0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62  y.** [sqlite3_db
156f0 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49  _status](D,[SQLI
15700 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
15710 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72  IDE],...) is zer
15720 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  o..** Any attemp
15730 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  t to change the 
15740 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
15750 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77   configuration w
15760 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  hen lookaside.**
15770 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73   memory is in us
15780 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e  e leaves the con
15790 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61  figuration uncha
157a0 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73  nged and returns
157b0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53   .** [SQLITE_BUS
157c0 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  Y].)^</dd>.**.**
157d0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
157e0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
157f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
15800 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
15810 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
15820 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f  disable the enfo
15830 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66  rcement of.** [f
15840 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74  oreign key const
15850 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20  raints].  There 
15860 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
15870 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
15880 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
15890 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
158a0 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
158b0 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b   0 to disable FK
158c0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a   enforcement,.**
158d0 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
158e0 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
158f0 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  nt or negative t
15900 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72  o leave FK enfor
15910 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e  cement.** unchan
15920 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ged.  The second
15930 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
15940 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
15950 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
15960 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
15970 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
15980 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66  e whether FK enf
15990 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20  orcement is off 
159a0 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  or on.** followi
159b0 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
159c0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
159d0 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
159e0 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
159f0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
15a00 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73  FK enforcement s
15a10 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
15a20 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
15a30 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
15a40 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
15a50 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e  BLE_TRIGGER</dt>
15a60 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
15a70 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
15a80 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
15a90 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  le [CREATE TRIGG
15aa0 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a  ER | triggers]..
15ab0 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
15ac0 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
15ad0 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
15ae0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
15af0 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
15b00 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
15b10 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c  isable triggers,
15b20 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
15b30 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20  enable triggers 
15b40 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
15b50 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
15b60 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54   unchanged..** T
15b70 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
15b80 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
15b90 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
15ba0 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
15bb0 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
15bc0 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
15bd0 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20  er triggers are 
15be0 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
15bf0 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  led.** following
15c00 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
15c10 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
15c20 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
15c30 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
15c40 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72  hich case the tr
15c50 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73  igger setting is
15c60 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
15c70 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
15c80 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
15c90 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
15ca0 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20  _LOOKASIDE      
15cb0 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20   1001  /* void* 
15cc0 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
15cd0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
15ce0 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20  IG_ENABLE_FKEY  
15cf0 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 20     1002  /* int 
15d00 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
15d10 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
15d20 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20  ENABLE_TRIGGER  
15d30 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74  1003  /* int int
15d40 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  * */.../*.** CAP
15d50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
15d60 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65   Disable Extende
15d70 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
15d80 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
15d90 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
15da0 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e  t_codes() routin
15db0 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  e enables or dis
15dc0 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78  ables the.** [ex
15dd0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
15de0 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20  des] feature of 
15df0 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74  SQLite. ^The ext
15e00 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20  ended result.** 
15e10 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c  codes are disabl
15e20 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f  ed by default fo
15e30 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d  r historical com
15e40 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69  patibility..*/.i
15e50 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
15e60 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
15e70 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
15e80 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
15e90 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73  PI3REF: Last Ins
15ea0 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20  ert Rowid.**.** 
15eb0 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61  ^Each entry in a
15ec0 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68  n SQLite table h
15ed0 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62  as a unique 64-b
15ee0 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74  it signed.** int
15ef0 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20  eger key called 
15f00 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f  the [ROWID | "ro
15f10 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69  wid"]. ^The rowi
15f20 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69  d is always avai
15f30 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75  lable.** as an u
15f40 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e  ndeclared column
15f50 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49   named ROWID, OI
15f60 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73  D, or _ROWID_ as
15f70 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a   long as those.*
15f80 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20  * names are not 
15f90 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70  also used by exp
15fa0 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
15fb0 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a   columns. ^If.**
15fc0 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61   the table has a
15fd0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20   column of type 
15fe0 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
15ff0 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20   KEY] then that 
16000 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f  column.** is ano
16010 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74  ther alias for t
16020 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20  he rowid..**.** 
16030 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
16040 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64  turns the [rowid
16050 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65  ] of the most re
16060 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66  cent.** successf
16070 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f  ul [INSERT] into
16080 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72   the database fr
16090 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  om the [database
160a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
160b0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
160c0 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66 20 53  ument.  ^As of S
160d0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
160e0 37 2e 37 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  7.7, this routin
160f0 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20 74 68  es.** records th
16100 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f  e last insert ro
16110 77 69 64 20 6f 66 20 62 6f 74 68 20 6f 72 64 69  wid of both ordi
16120 6e 61 72 79 20 74 61 62 6c 65 73 20 61 6e 64 20  nary tables and 
16130 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
16140 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63  ..** ^If no succ
16150 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73  essful [INSERT]s
16160 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63  .** have ever oc
16170 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64  curred on that d
16180 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16190 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75  on, zero is retu
161a0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  rned..**.** ^(If
161b0 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63   an [INSERT] occ
161c0 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
161d0 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61  gger or within a
161e0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
161f0 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  .** method, then
16200 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
16210 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72  ll return the [r
16220 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73  owid] of the ins
16230 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20  erted.** row as 
16240 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67  long as the trig
16250 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74  ger or virtual t
16260 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72  able method is r
16270 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f  unning..** But o
16280 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
16290 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  or virtual table
162a0 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68   method ends, th
162b0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
162c0 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75   .** by this rou
162d0 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20  tine reverts to 
162e0 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f  what it was befo
162f0 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  re the trigger o
16300 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62  r virtual.** tab
16310 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e  le method began.
16320 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e  )^.**.** ^An [IN
16330 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
16340 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
16350 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
16360 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
16370 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
16380 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
16390 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
163a0 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
163b0 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73   routine.  ^Thus
163c0 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
163d0 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
163e0 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
163f0 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
16400 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
16410 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
16420 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
16430 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
16440 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
16450 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
16460 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20    ^(When INSERT 
16470 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
16480 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
16490 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
164a0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
164b0 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
164c0 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
164d0 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
164e0 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
164f0 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
16500 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
16510 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
16520 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
16530 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
16540 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
16550 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
16560 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  e.)^.**.** ^For 
16570 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
16580 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
16590 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e   [INSERT] is con
165a0 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
165b0 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
165c0 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
165d0 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
165e0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ck..**.** This f
165f0 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73  unction is acces
16600 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61  sible to SQL sta
16610 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a  tements via the.
16620 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f  ** [last_insert_
16630 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63  rowid() SQL func
16640 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
16650 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
16660 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
16670 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
16680 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
16690 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
166a0 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
166b0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
166c0 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
166d0 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
166e0 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
166f0 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
16700 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
16710 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
16720 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
16730 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
16740 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
16750 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
16760 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
16770 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
16780 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
16790 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73  rt [rowid]..*/.s
167a0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
167b0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
167c0 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
167d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
167e0 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
167f0 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
16800 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  fied.**.** ^This
16810 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
16820 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
16830 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68  database rows th
16840 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a  at were changed.
16850 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f  ** or inserted o
16860 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65  r deleted by the
16870 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
16880 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61  ompleted SQL sta
16890 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65  tement.** on the
168a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
168b0 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
168c0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61   by the first pa
168d0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e  rameter..** ^(On
168e0 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20  ly changes that 
168f0 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65  are directly spe
16900 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49  cified by the [I
16910 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
16920 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ,.** or [DELETE]
16930 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63   statement are c
16940 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61  ounted.  Auxilia
16950 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
16960 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73  d by.** triggers
16970 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79   or [foreign key
16980 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f   actions] are no
16990 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65  t counted.)^ Use
169a0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
169b0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
169c0 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69  ] function to fi
169d0 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  nd the total num
169e0 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a  ber of changes.*
169f0 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e  * including chan
16a00 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72  ges caused by tr
16a10 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69  iggers and forei
16a20 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a  gn key actions..
16a30 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74  **.** ^Changes t
16a40 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72  o a view that ar
16a50 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61  e simulated by a
16a60 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  n [INSTEAD OF tr
16a70 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f  igger].** are no
16a80 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79  t counted.  Only
16a90 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e   real table chan
16aa0 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ges are counted.
16ab0 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20  .**.** ^(A "row 
16ac0 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61  change" is a cha
16ad0 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20  nge to a single 
16ae0 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  row of a single 
16af0 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20  table.** caused 
16b00 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45  by an INSERT, DE
16b10 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20  LETE, or UPDATE 
16b20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73  statement.  Rows
16b30 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61   that.** are cha
16b40 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66  nged as side eff
16b50 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45  ects of [REPLACE
16b60 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  ] constraint res
16b70 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c  olution,.** roll
16b80 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63  back, ABORT proc
16b90 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41  essing, [DROP TA
16ba0 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20  BLE], or by any 
16bb0 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69  other.** mechani
16bc0 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  sms do not count
16bd0 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63   as direct row c
16be0 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  hanges.)^.**.** 
16bf0 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65  A "trigger conte
16c00 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f  xt" is a scope o
16c10 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74  f execution that
16c20 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65   begins and.** e
16c30 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72  nds with the scr
16c40 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45  ipt of a [CREATE
16c50 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
16c60 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51  er]. .** Most SQ
16c70 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
16c80 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75  .** evaluated ou
16c90 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69  tside of any tri
16ca0 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74  gger.  This is t
16cb0 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a  he "top level".*
16cc0 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
16cd0 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72  t.  If a trigger
16ce0 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20   fires from the 
16cf0 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20  top level, a.** 
16d00 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
16d10 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66  ext is entered f
16d20 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20  or the duration 
16d30 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74  of that one.** t
16d40 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67  rigger.  Subtrig
16d50 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63  gers create subc
16d60 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69  ontexts for thei
16d70 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  r duration..**.*
16d80 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  * ^Calling [sqli
16d90 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b  te3_exec()] or [
16da0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
16db0 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73  recursively does
16dc0 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61  .** not create a
16dd0 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e   new trigger con
16de0 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  text..**.** ^Thi
16df0 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
16e00 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
16e10 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
16e20 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f  ges in the.** mo
16e30 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
16e40 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
16e50 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
16e60 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  thin the same.**
16e70 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
16e80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77  ..**.** ^Thus, w
16e90 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  hen called from 
16ea0 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74  the top level, t
16eb0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
16ec0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  urns the.** numb
16ed0 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e  er of changes in
16ee0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
16ef0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
16f00 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
16f10 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64  at also occurred
16f20 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65   at the top leve
16f30 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65  l.  ^(Within the
16f40 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67   body of a trigg
16f50 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  er,.** the sqlit
16f60 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74  e3_changes() int
16f70 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61  erface can be ca
16f80 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  lled to find the
16f90 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
16fa0 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
16fb0 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
16fc0 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44  eted INSERT, UPD
16fd0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
16fe0 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  * statement with
16ff0 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74  in the body of t
17000 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e  he same trigger.
17010 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
17020 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64   number returned
17030 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
17040 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75  e changes.** cau
17050 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65  sed by subtrigge
17060 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68  rs since those h
17070 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f  ave their own co
17080 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  ntext.)^.**.** S
17090 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
170a0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
170b0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
170c0 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
170d0 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
170e0 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73  and the [changes
170f0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
17100 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
17110 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
17120 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
17130 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
17140 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
17150 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  ile [sqlite3_cha
17160 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
17170 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
17180 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  e returned.** is
17190 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
171a0 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
171b0 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
171c0 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  3_changes(sqlite
171d0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
171e0 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62  3REF: Total Numb
171f0 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
17200 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ied.**.** ^This 
17210 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
17220 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
17230 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ow changes cause
17240 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a  d by [INSERT],.*
17250 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44  * [UPDATE] or [D
17260 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
17270 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74  s since the [dat
17280 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17290 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a  ] was opened..**
172a0 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74   ^(The count ret
172b0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
172c0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
172d0 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68   includes all ch
172e0 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c  anges.** from al
172f0 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  l [CREATE TRIGGE
17300 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e  R | trigger] con
17310 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65  texts and change
17320 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f  s made by.** [fo
17330 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
17340 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  s]. However,.** 
17350 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e  the count does n
17360 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
17370 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  es used to imple
17380 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63  ment [REPLACE] c
17390 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64  onstraints,.** d
173a0 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41  o rollbacks or A
173b0 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
173c0 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d   or [DROP TABLE]
173d0 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68   processing.  Th
173e0 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20  e.** count does 
173f0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73  not include rows
17400 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 20 66   of views that f
17410 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20  ire an [INSTEAD 
17420 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20  OF trigger],.** 
17430 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e  though if the IN
17440 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
17450 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
17460 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65  f its own, those
17470 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65   changes .** are
17480 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e   counted.)^.** ^
17490 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  The sqlite3_tota
174a0 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63  l_changes() func
174b0 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20  tion counts the 
174c0 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20  changes as soon 
174d0 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  as.** the statem
174e0 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74  ent that makes t
174f0 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64  hem is completed
17500 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65   (when the state
17510 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69  ment handle.** i
17520 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  s passed to [sql
17530 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
17540 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
17550 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  ze()])..**.** Se
17560 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
17570 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
17580 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
17590 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
175a0 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
175b0 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28   [total_changes(
175c0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
175d0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
175e0 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
175f0 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
17600 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
17610 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
17620 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  le [sqlite3_tota
17630 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  l_changes()] is 
17640 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
17650 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
17660 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ed is unpredicta
17670 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
17680 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
17690 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
176a0 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
176b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
176c0 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e   Interrupt A Lon
176d0 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a  g-Running Query.
176e0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
176f0 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
17700 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
17710 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
17720 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
17730 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
17740 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
17750 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
17760 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
17770 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
17780 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
17790 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
177a0 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
177b0 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
177c0 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
177d0 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
177e0 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
177f0 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
17800 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20   ^It is safe to 
17810 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
17820 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20  e from a thread 
17830 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74  different from t
17840 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61  he.** thread tha
17850 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72  t is currently r
17860 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  unning the datab
17870 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  ase operation.  
17880 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74  But it.** is not
17890 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
178a0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
178b0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
178c0 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20  ection] that.** 
178d0 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67  is closed or mig
178e0 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20  ht close before 
178f0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
17900 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
17910 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70  ** ^If an SQL op
17920 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20  eration is very 
17930 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20  nearly finished 
17940 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
17950 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  .** sqlite3_inte
17960 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65  rrupt() is calle
17970 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74  d, then it might
17980 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70   not have an opp
17990 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62  ortunity.** to b
179a0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e  e interrupted an
179b0 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65  d might continue
179c0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
179d0 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70  **.** ^An SQL op
179e0 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
179f0 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
17a00 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
17a10 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e  INTERRUPT]..** ^
17a20 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74  If the interrupt
17a30 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  ed SQL operation
17a40 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55   is an INSERT, U
17a50 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
17a60 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69  .** that is insi
17a70 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  de an explicit t
17a80 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
17a90 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e   the entire tran
17aa0 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20  saction.** will 
17ab0 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
17ac0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a  utomatically..**
17ad0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
17ae0 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61  _interrupt(D) ca
17af0 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20  ll is in effect 
17b00 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e  until all curren
17b10 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53  tly running.** S
17b20 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e  QL statements on
17b30 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
17b40 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74  ction] D complet
17b50 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c  e.  ^Any new SQL
17b60 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
17b70 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
17b80 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
17b90 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
17ba0 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68  ll and before th
17bb0 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74  e .** running st
17bc0 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73  atements reaches
17bd0 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72   zero are interr
17be0 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79  upted as if they
17bf0 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e   had been.** run
17c00 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68  ning prior to th
17c10 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
17c20 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65  upt() call.  ^Ne
17c30 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
17c40 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
17c50 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72  rted after the r
17c60 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
17c70 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a   count reaches z
17c80 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65  ero are.** not e
17c90 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73  ffected by the s
17ca0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
17cb0 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  ()..** ^A call t
17cc0 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
17cd0 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75  upt(D) that occu
17ce0 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72  rs when there ar
17cf0 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  e no running.** 
17d00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
17d10 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61  s a no-op and ha
17d20 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
17d30 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
17d40 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
17d50 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
17d60 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
17d70 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  call returns..**
17d80 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62  .** If the datab
17d90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
17da0 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c  loses while [sql
17db0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
17dc0 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20  ].** is running 
17dd0 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20  then bad things 
17de0 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70  will likely happ
17df0 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  en..*/.void sqli
17e00 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71  te3_interrupt(sq
17e10 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
17e20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
17e30 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
17e40 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c  atement Is Compl
17e50 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ete.**.** These 
17e60 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
17e70 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61  ful during comma
17e80 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
17e90 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
17ea0 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
17eb0 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
17ec0 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70  s to form a comp
17ed0 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
17ee0 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
17ef0 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
17f00 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
17f10 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
17f20 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
17f30 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65  r parsing.  ^The
17f40 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
17f50 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75  rn 1 if the inpu
17f60 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
17f70 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
17f80 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
17f90 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e  nt.  ^A statemen
17fa0 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62  t is judged to b
17fb0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66  e.** complete if
17fc0 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20   it ends with a 
17fd0 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20  semicolon token 
17fe0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65  and is not a pre
17ff0 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c  fix of a.** well
18000 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54  -formed CREATE T
18010 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
18020 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74  .  ^Semicolons t
18030 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64  hat are embedded
18040 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e   within.** strin
18050 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75  g literals or qu
18060 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20  oted identifier 
18070 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74  names or comment
18080 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64  s are not.** ind
18090 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20  ependent tokens 
180a0 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f  (they are part o
180b0 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77  f the token in w
180c0 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a  hich they are.**
180d0 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74   embedded) and t
180e0 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  hus do not count
180f0 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20   as a statement 
18100 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68  terminator.  ^Wh
18110 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20  itespace.** and 
18120 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f  comments that fo
18130 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73  llow the final s
18140 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e  emicolon are ign
18150 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ored..**.** ^The
18160 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
18170 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74  rn 0 if the stat
18180 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c  ement is incompl
18190 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d  ete.  ^If a.** m
181a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
181b0 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c   fails, then SQL
181c0 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74  ITE_NOMEM is ret
181d0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
181e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20  ese routines do 
181f0 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51  not parse the SQ
18200 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75  L statements thu
18210 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65  s.** will not de
18220 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c  tect syntactical
18230 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c  ly incorrect SQL
18240 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c  ..**.** ^(If SQL
18250 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ite has not been
18260 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69   initialized usi
18270 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ng [sqlite3_init
18280 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20  ialize()] prior 
18290 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20  .** to invoking 
182a0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
182b0 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65  16() then sqlite
182c0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
182d0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74  s invoked.** aut
182e0 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
182f0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
18300 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69  ().  If that ini
18310 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c  tialization fail
18320 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  s,.** then the r
18330 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
18340 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
18350 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f  e16() will be no
18360 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64  n-zero.** regard
18370 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
18380 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74  or not the input
18390 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65   SQL is complete
183a0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  .)^.**.** The in
183b0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
183c0 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74  complete()] must
183d0 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
183e0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73  nated.** UTF-8 s
183f0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
18400 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
18410 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
18420 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
18430 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
18440 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
18450 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
18460 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
18470 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20  _complete(const 
18480 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20  char *sql);.int 
18490 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
184a0 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  16(const void *s
184b0 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ql);../*.** CAPI
184c0 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
184d0 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e   Callback To Han
184e0 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  dle SQLITE_BUSY 
184f0 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  Errors.**.** ^Th
18500 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
18510 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
18520 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62  ion that might b
18530 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
18540 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74  er.** an attempt
18550 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
18560 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
18570 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74  e that another t
18580 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63  hread.** or proc
18590 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a  ess has locked..
185a0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75  **.** ^If the bu
185b0 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
185c0 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
185d0 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
185e0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
185f0 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
18600 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
18610 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
18620 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68  he lock.  ^If th
18630 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
18640 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
18650 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
18660 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  k might be invok
18670 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
18680 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
18690 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
186a0 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   to the busy han
186b0 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
186c0 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
186d0 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
186e0 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
186f0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
18700 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e  sy_handler().  ^
18710 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
18720 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75  ent to.** the bu
18730 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
18740 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
18750 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
18760 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
18770 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
18780 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f  oked for this lo
18790 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  cking event.  ^I
187a0 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
187b0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
187c0 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
187d0 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
187e0 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
187f0 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
18800 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
18810 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
18820 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20  ERR_BLOCKED] is 
18830 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66  returned..** ^If
18840 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
18850 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
18860 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
18870 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
18880 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
18890 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67  base for reading
188a0 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72   and the cycle r
188b0 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  epeats..**.** Th
188c0 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20  e presence of a 
188d0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65  busy handler doe
188e0 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20  s not guarantee 
188f0 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20  that it will be 
18900 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20  invoked.** when 
18910 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f  there is lock co
18920 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51  ntention. ^If SQ
18930 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20  Lite determines 
18940 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  that invoking th
18950 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65  e busy.** handle
18960 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  r could result i
18970 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74  n a deadlock, it
18980 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61   will go ahead a
18990 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
189a0 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53  E_BUSY].** or [S
189b0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
189c0 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20  KED] instead of 
189d0 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
189e0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f  y handler..** Co
189f0 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69  nsider a scenari
18a00 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63  o where one proc
18a10 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
18a20 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a   read lock that.
18a30 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20  ** it is trying 
18a40 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20  to promote to a 
18a50 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e  reserved lock an
18a60 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72  d.** a second pr
18a70 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
18a80 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
18a90 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69   that it is tryi
18aa0 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ng.** to promote
18ab0 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65   to an exclusive
18ac0 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73   lock.  The firs
18ad0 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  t process cannot
18ae0 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61   proceed.** beca
18af0 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
18b00 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
18b10 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70  and the second p
18b20 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a  rocess cannot.**
18b30 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65   proceed because
18b40 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
18b50 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66  y the first.  If
18b60 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a   both processes.
18b70 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75  ** invoke the bu
18b80 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69  sy handlers, nei
18b90 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61  ther will make a
18ba0 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68  ny progress.  Th
18bb0 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69  erefore,.** SQLi
18bc0 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  te returns [SQLI
18bd0 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65  TE_BUSY] for the
18be0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20   first process, 
18bf0 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73  hoping that this
18c00 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20  .** will induce 
18c10 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
18c20 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73  s to release its
18c30 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61   read lock and a
18c40 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f  llow.** the seco
18c50 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72  nd process to pr
18c60 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oceed..**.** ^Th
18c70 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63  e default busy c
18c80 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e  allback is NULL.
18c90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
18ca0 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20  ITE_BUSY] error 
18cb0 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  is converted to 
18cc0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
18cd0 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53  OCKED].** when S
18ce0 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20  QLite is in the 
18cf0 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67  middle of a larg
18d00 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68  e transaction wh
18d10 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63  ere all the.** c
18d20 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20  hanges will not 
18d30 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d  fit into the in-
18d40 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53  memory cache.  S
18d50 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c  QLite will.** al
18d60 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53  ready hold a RES
18d70 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68  ERVED lock on th
18d80 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
18d90 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a   but it needs.**
18da0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73   to promote this
18db0 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49   lock to EXCLUSI
18dc0 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61  VE so that it ca
18dd0 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a  n spill cache.**
18de0 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20   pages into the 
18df0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
18e00 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f  thout harm to co
18e10 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64  ncurrent.** read
18e20 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20  ers.  ^If it is 
18e30 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74  unable to promot
18e40 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e  e the lock, then
18e50 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a   the in-memory.*
18e60 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20  * cache will be 
18e70 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e  left in an incon
18e80 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e  sistent state an
18e90 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a  d so the error.*
18ea0 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74  * code is promot
18eb0 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61  ed from the rela
18ec0 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53  tively benign [S
18ed0 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a  QLITE_BUSY] to.*
18ee0 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72  * the more sever
18ef0 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  e [SQLITE_IOERR_
18f00 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73  BLOCKED].  ^This
18f10 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d   error code prom
18f20 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20  otion.** forces 
18f30 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c  an automatic rol
18f40 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61  lback of the cha
18f50 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a  nges.  See the.*
18f60 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74  * <a href="/cvst
18f70 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75  rac/wiki?p=Corru
18f80 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
18f90 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72  syError">.** Cor
18fa0 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
18fb0 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69  BusyError</a> wi
18fc0 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69  ki page for a di
18fd0 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a  scussion of why.
18fe0 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72  ** this is impor
18ff0 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  tant..**.** ^(Th
19000 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
19010 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
19020 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f  ndler defined fo
19030 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  r each.** [datab
19040 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
19050 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20    Setting a new 
19060 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65  busy handler cle
19070 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69  ars any.** previ
19080 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65  ously set handle
19090 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74  r.)^  ^Note that
190a0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
190b0 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
190c0 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73  ].** will also s
190d0 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20  et or clear the 
190e0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
190f0 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c  .** The busy cal
19100 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74  lback should not
19110 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e   take any action
19120 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74  s which modify t
19130 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
19140 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
19150 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
19160 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75  handler.  Any su
19170 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65  ch actions.** re
19180 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
19190 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a  d behavior..** .
191a0 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  ** A busy handle
191b0 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  r must not close
191c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
191d0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b  nnection.** or [
191e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
191f0 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  nt] that invoked
19200 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
19210 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
19220 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
19230 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
19240 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
19250 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
19260 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
19270 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54  Timeout.**.** ^T
19280 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
19290 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
192a0 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
192b0 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c  handler] that sl
192c0 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70  eeps.** for a sp
192d0 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f  ecified amount o
192e0 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61  f time when a ta
192f0 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
19300 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  ^The handler.** 
19310 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
19320 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
19330 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
19340 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
19350 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
19360 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66  ccumulated.  ^Af
19370 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73  ter at least "ms
19380 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
19390 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
193a0 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
193b0 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
193c0 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
193d0 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
193e0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
193f0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
19400 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  LOCKED]..**.** ^
19410 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
19420 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
19430 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
19440 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
19450 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
19460 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
19470 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
19480 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
19490 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
194a0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
194b0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
194c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61  onnection] any a
194d0 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
194e0 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
194f0 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
19500 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
19510 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
19520 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
19530 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
19540 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
19550 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
19560 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
19570 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )^.*/.int sqlite
19580 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73  3_busy_timeout(s
19590 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29  qlite3*, int ms)
195a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
195b0 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52  F: Convenience R
195c0 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e  outines For Runn
195d0 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a  ing Queries.**.*
195e0 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61  * This is a lega
195f0 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  cy interface tha
19600 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66  t is preserved f
19610 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
19620 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55  patibility..** U
19630 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  se of this inter
19640 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f  face is not reco
19650 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44  mmended..**.** D
19660 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
19670 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
19680 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
19690 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
196a0 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
196b0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
196c0 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
196d0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
196e0 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
196f0 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
19700 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
19710 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
19720 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
19730 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
19740 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
19750 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
19760 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
19770 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
19780 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
19790 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
197a0 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
197b0 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
197c0 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
197d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
197e0 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
197f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
19800 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
19810 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
19820 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
19830 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
19840 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
19850 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
19860 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
19870 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
19880 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
19890 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
198a0 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
198b0 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
198c0 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
198d0 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
198e0 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
198f0 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
19900 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
19910 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
19920 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
19930 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
19940 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
19950 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
19960 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
19970 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
19980 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
19990 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
199a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
199b0 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
199c0 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
199d0 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
199e0 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
199f0 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
19a00 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
19a10 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
19a20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
19a30 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
19a40 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
19a50 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
19a60 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
19a70 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
19a80 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
19a90 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  ^(As an example 
19aa0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
19ab0 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70  ble format, supp
19ac0 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75  ose a query resu
19ad0 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c  lt.** is as foll
19ae0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
19af0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
19b00 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20         Name     
19b10 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20     | Age.**     
19b20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d     -------------
19b30 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20  ----------.**   
19b40 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20       Alice      
19b50 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20   | 43.**        
19b60 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38  Bob         | 28
19b70 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79  .**        Cindy
19b80 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c         | 21.** <
19b90 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
19ba0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61  e>.**.** There a
19bb0 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d  re two column (M
19bc0 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72  ==2) and three r
19bd0 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75  ows (N==3).  Thu
19be0 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  s the.** result 
19bf0 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72  table has 8 entr
19c00 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68  ies.  Suppose th
19c10 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
19c20 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
19c30 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a  n array names az
19c40 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a  Result.  Then az
19c50 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69  Result holds thi
19c60 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a  s content:.**.**
19c70 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
19c80 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  e>.**        azR
19c90 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22  esult&#91;0] = "
19ca0 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  Name";.**       
19cb0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d   azResult&#91;1]
19cc0 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20   = "Age";.**    
19cd0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
19ce0 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a  ;2] = "Alice";.*
19cf0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
19d00 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b  t&#91;3] = "43";
19d10 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
19d20 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f  ult&#91;4] = "Bo
19d30 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  b";.**        az
19d40 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20  Result&#91;5] = 
19d50 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "28";.**        
19d60 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20  azResult&#91;6] 
19d70 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20  = "Cindy";.**   
19d80 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
19d90 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20  1;7] = "21";.** 
19da0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
19db0 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
19dc0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
19dd0 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76  le() function ev
19de0 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d  aluates one or m
19df0 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ore.** semicolon
19e00 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73  -separated SQL s
19e10 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
19e20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
19e30 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67   UTF-8.** string
19e40 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61   of its 2nd para
19e50 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
19e60 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
19e70 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74   to the.** point
19e80 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20  er given in its 
19e90 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  3rd parameter..*
19ea0 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61  *.** After the a
19eb0 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66  pplication has f
19ec0 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65  inished with the
19ed0 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c   result from sql
19ee0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
19ef0 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73  ,.** it must pas
19f00 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  s the result tab
19f10 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  le pointer to sq
19f20 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
19f30 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  () in order to.*
19f40 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
19f50 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
19f60 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65  lloced.  Because
19f70 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a   of the way the.
19f80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
19f90 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69  oc()] happens wi
19fa0 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  thin sqlite3_get
19fb0 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61  _table(), the ca
19fc0 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  lling.** functio
19fd0 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
19fe0 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  o call [sqlite3_
19ff0 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
1a000 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69  .  Only.** [sqli
1a010 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1a020 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
1a030 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
1a040 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
1a050 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
1a060 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1a070 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
1a080 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61  implemented as a
1a090 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
1a0a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
1a0b0 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ()].  The sqlite
1a0c0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f  3_get_table() ro
1a0d0 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68  utine does not h
1a0e0 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ave access.** to
1a0f0 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61   any internal da
1a100 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66  ta structures of
1a110 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65   SQLite.  It use
1a120 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69  s only the publi
1a130 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64  c.** interface d
1a140 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73  efined here.  As
1a150 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20   a consequence, 
1a160 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
1a170 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70  r in the.** wrap
1a180 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64  per layer outsid
1a190 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61  e of the interna
1a1a0 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  l [sqlite3_exec(
1a1b0 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a  )] call are not.
1a1c0 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20  ** reflected in 
1a1d0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1a1e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
1a1f0 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  code()] or.** [s
1a200 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1a210 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1a220 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
1a230 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1a240 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
1a250 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
1a260 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
1a270 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
1a280 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
1a290 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
1a2a0 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
1a2b0 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
1a2c0 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
1a2d0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
1a2e0 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
1a2f0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1a300 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
1a310 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
1a320 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
1a330 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
1a340 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
1a350 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
1a360 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
1a370 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69  n here */.);.voi
1a380 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  d sqlite3_free_t
1a390 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
1a3a0 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
1a3b0 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
1a3c0 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
1a3d0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1a3e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1a3f0 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f  re work-alikes o
1a400 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
1a410 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
1a420 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
1a430 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1a440 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ary..**.** ^The 
1a450 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1a460 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d  ) and sqlite3_vm
1a470 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1a480 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a  s write their.**
1a490 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65   results into me
1a4a0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
1a4b0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
1a4c0 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74  oc()]..** The st
1a4d0 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
1a4e0 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74  y these two rout
1a4f0 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a  ines should be.*
1a500 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73  * released by [s
1a510 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20  qlite3_free()]. 
1a520 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20   ^Both routines 
1a530 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
1a540 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
1a550 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
1a560 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
1a570 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d  cate enough.** m
1a580 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
1a590 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
1a5a0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ng..**.** ^(The 
1a5b0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1a5c0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
1a5d0 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e  milar to "snprin
1a5e0 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68  tf()" from.** th
1a5f0 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
1a600 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c  rary.  The resul
1a610 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  t is written int
1a620 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20  o the.** buffer 
1a630 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20  supplied as the 
1a640 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1a650 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67   whose size is g
1a660 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66  iven by.** the f
1a670 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
1a680 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72  Note that the or
1a690 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  der of the.** fi
1a6a0 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65  rst two paramete
1a6b0 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66  rs is reversed f
1a6c0 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29  rom snprintf().)
1a6d0 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a  ^  This is an.**
1a6e0 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69   historical acci
1a6f0 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74  dent that cannot
1a700 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75   be fixed withou
1a710 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61  t breaking.** ba
1a720 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1a730 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61  ility.  ^(Note a
1a740 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33  lso that sqlite3
1a750 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72  _snprintf().** r
1a760 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1a770 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69   to its buffer i
1a780 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75  nstead of the nu
1a790 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61  mber of.** chara
1a7a0 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77  cters actually w
1a7b0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
1a7c0 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64  buffer.)^  We ad
1a7d0 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  mit that.** the 
1a7e0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
1a7f0 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75  ters written wou
1a800 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65  ld be a more use
1a810 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  ful return.** va
1a820 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f  lue but we canno
1a830 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70  t change the imp
1a840 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
1a850 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1a860 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74  ).** now without
1a870 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74   breaking compat
1a880 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ibility..**.** ^
1a890 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62  As long as the b
1a8a0 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72  uffer size is gr
1a8b0 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c  eater than zero,
1a8c0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1a8d0 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  f().** guarantee
1a8e0 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65  s that the buffe
1a8f0 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  r is always zero
1a900 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
1a910 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
1a920 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65  meter "n" is the
1a930 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74   total size of t
1a940 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75  he buffer, inclu
1a950 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a  ding space for.*
1a960 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  * the zero termi
1a970 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c  nator.  So the l
1a980 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68  ongest string th
1a990 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65  at can be comple
1a9a0 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20  tely.** written 
1a9b0 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72  will be n-1 char
1a9c0 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  acters..**.** ^T
1a9d0 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  he sqlite3_vsnpr
1a9e0 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
1a9f0 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73  s a varargs vers
1aa00 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
1aa10 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a  nprintf()..**.**
1aa20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1aa30 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f  all implement so
1aa40 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f  me additional fo
1aa50 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69  rmatting.** opti
1aa60 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65  ons that are use
1aa70 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63  ful for construc
1aa80 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  ting SQL stateme
1aa90 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74  nts..** All of t
1aaa0 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28  he usual printf(
1aab0 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  ) formatting opt
1aac0 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20  ions apply.  In 
1aad0 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a  addition, there.
1aae0 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20  ** is are "%q", 
1aaf0 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f  "%Q", and "%z" o
1ab00 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ptions..**.** ^(
1ab10 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f  The %q option wo
1ab20 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74  rks like %s in t
1ab30 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74  hat it substitut
1ab40 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  es a nul-termina
1ab50 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72  ted.** string fr
1ab60 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  om the argument 
1ab70 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c  list.  But %q al
1ab80 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79  so doubles every
1ab90 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e   '\'' character.
1aba0 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e  .** %q is design
1abb0 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
1abc0 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  e a string liter
1abd0 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69  al.)^  By doubli
1abe0 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20  ng each '\''.** 
1abf0 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63  character it esc
1ac00 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63  apes that charac
1ac10 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69  ter and allows i
1ac20 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64  t to be inserted
1ac30 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72   into.** the str
1ac40 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  ing..**.** For e
1ac50 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74  xample, assume t
1ac60 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62  he string variab
1ac70 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e  le zText contain
1ac80 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77  s text as follow
1ac90 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1aca0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1acb0 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74  har *zText = "It
1acc0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22  's a happy day!"
1acd0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1ace0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f  ckquote>.**.** O
1acf0 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20  ne can use this 
1ad00 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73  text in an SQL s
1ad10 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c  tatement as foll
1ad20 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1ad30 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1ad40 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
1ad50 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
1ad60 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1ad70 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20   VALUES('%q')", 
1ad80 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
1ad90 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
1ada0 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
1adb0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
1adc0 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
1add0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1ade0 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71  * Because the %q
1adf0 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69   format string i
1ae00 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27  s used, the '\''
1ae10 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54   character in zT
1ae20 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65  ext.** is escape
1ae30 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65  d and the SQL ge
1ae40 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f  nerated is as fo
1ae50 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1ae60 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1ae70 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
1ae80 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
1ae90 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  ''s a happy day!
1aea0 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ').** </pre></bl
1aeb0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1aec0 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e  This is correct.
1aed0 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73    Had we used %s
1aee0 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20   instead of %q, 
1aef0 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51  the generated SQ
1af00 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20  L.** would have 
1af10 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73  looked like this
1af20 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1af30 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
1af40 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
1af50 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20   VALUES('It's a 
1af60 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a  happy day!');.**
1af70 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1af80 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
1af90 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69  second example i
1afa0 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20  s an SQL syntax 
1afb0 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e  error.  As a gen
1afc0 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68  eral rule you sh
1afd0 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75  ould.** always u
1afe0 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66  se %q instead of
1aff0 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69   %s when inserti
1b000 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73  ng text into a s
1b010 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a  tring literal..*
1b020 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70  *.** ^(The %Q op
1b030 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1b040 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73  %q except it als
1b050 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75  o adds single qu
1b060 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74  otes around.** t
1b070 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  he outside of th
1b080 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20  e total string. 
1b090 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69   Additionally, i
1b0a0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1b0b0 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65  in the.** argume
1b0c0 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c  nt list is a NUL
1b0d0 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75  L pointer, %Q su
1b0e0 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65  bstitutes the te
1b0f0 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f  xt "NULL" (witho
1b100 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f  ut.** single quo
1b110 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72  tes).)^  So, for
1b120 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f   example, one co
1b130 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c  uld say:.**.** <
1b140 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1b150 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
1b160 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
1b170 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
1b180 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22  able VALUES(%Q)"
1b190 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
1b1a0 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
1b1b0 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
1b1c0 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
1b1d0 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
1b1e0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1b1f0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f  .** The code abo
1b200 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61  ve will render a
1b210 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61   correct SQL sta
1b220 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53  tement in the zS
1b230 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65  QL.** variable e
1b240 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74  ven if the zText
1b250 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e   variable is a N
1b260 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
1b270 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f  ** ^(The "%z" fo
1b280 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
1b290 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20  works like "%s" 
1b2a0 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  but with the.** 
1b2b0 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66  addition that af
1b2c0 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68  ter the string h
1b2d0 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64  as been read and
1b2e0 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20   copied into.** 
1b2f0 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c  the result, [sql
1b300 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20  ite3_free()] is 
1b310 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e  called on the in
1b320 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f  put string.)^.*/
1b330 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d  .char *sqlite3_m
1b340 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1b350 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73  r*,...);.char *s
1b360 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
1b370 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
1b380 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c  list);.char *sql
1b390 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e  ite3_snprintf(in
1b3a0 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
1b3b0 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20  ar*, ...);.char 
1b3c0 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e  *sqlite3_vsnprin
1b3d0 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
1b3e0 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
1b3f0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1b400 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
1b410 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d  cation Subsystem
1b420 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  .**.** The SQLit
1b430 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73  e core uses thes
1b440 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73  e three routines
1b450 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
1b460 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20  own.** internal 
1b470 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1b480 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20  n needs. "Core" 
1b490 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
1b4a0 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73  sentence.** does
1b4b0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65   not include ope
1b4c0 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
1b4d0 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65  ecific VFS imple
1b4e0 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a  mentation.  The.
1b4f0 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75  ** Windows VFS u
1b500 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f  ses native mallo
1b510 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
1b520 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f  or some operatio
1b530 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
1b540 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1b550 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1b560 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62  a pointer to a b
1b570 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  lock.** of memor
1b580 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  y at least N byt
1b590 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68  es in length, wh
1b5a0 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72  ere N is the par
1b5b0 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73  ameter..** ^If s
1b5c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1b5d0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74  is unable to obt
1b5e0 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66  ain sufficient f
1b5f0 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69  ree.** memory, i
1b600 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  t returns a NULL
1b610 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74   pointer.  ^If t
1b620 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74  he parameter N t
1b630 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  o.** sqlite3_mal
1b640 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
1b650 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73   negative then s
1b660 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1b670 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c  returns.** a NUL
1b680 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1b690 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
1b6a0 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20  3_free() with a 
1b6b0 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73  pointer previous
1b6c0 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ly returned.** b
1b6d0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
1b6e0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
1b6f0 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73  alloc() releases
1b700 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a   that memory so.
1b710 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  ** that it might
1b720 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68   be reused.  ^Th
1b730 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  e sqlite3_free()
1b740 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61   routine is.** a
1b750 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c   no-op if is cal
1b760 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
1b770 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e  pointer.  Passin
1b780 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  g a NULL pointer
1b790 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  .** to sqlite3_f
1b7a0 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73  ree() is harmles
1b7b0 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20  s.  After being 
1b7c0 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a  freed, memory.**
1b7d0 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20   should neither 
1b7e0 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74  be read nor writ
1b7f0 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69  ten.  Even readi
1b800 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72  ng previously fr
1b810 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69  eed.** memory mi
1b820 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20  ght result in a 
1b830 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
1b840 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  lt or other seve
1b850 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d  re error..** Mem
1b860 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20  ory corruption, 
1b870 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
1b880 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73  ault, or other s
1b890 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  evere error.** m
1b8a0 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73  ight result if s
1b8b0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
1b8c0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e   called with a n
1b8d0 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  on-NULL pointer 
1b8e0 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20  that.** was not 
1b8f0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
1b900 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
1b910 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1b920 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  c()..**.** ^(The
1b930 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1b940 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
1b950 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20  empts to resize 
1b960 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72  a.** prior memor
1b970 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
1b980 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
1b990 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20  tes, where N is 
1b9a0 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  the.** second pa
1b9b0 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65  rameter.  The me
1b9c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1b9d0 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73  to be resized is
1b9e0 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61   the first.** pa
1b9f0 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20  rameter.)^ ^ If 
1ba00 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1ba10 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1ba20 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61  ealloc().** is a
1ba30 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
1ba40 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20  en its behavior 
1ba50 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
1ba60 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
1ba70 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65  e3_malloc(N) whe
1ba80 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
1ba90 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
1baa0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1bab0 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65  )..** ^If the se
1bac0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
1bad0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1bae0 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a  c() is zero or.*
1baf0 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  * negative then 
1bb00 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
1bb10 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65  exactly the same
1bb20 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   as calling.** s
1bb30 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77  qlite3_free(P) w
1bb40 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69  here P is the fi
1bb50 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
1bb60 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1bb70 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f  ()..** ^sqlite3_
1bb80 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
1bb90 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1bba0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1bbb0 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
1bbc0 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
1bbd0 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66  e or NULL if suf
1bbe0 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69  ficient memory i
1bbf0 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
1bc00 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73  * ^If M is the s
1bc10 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
1bc20 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
1bc30 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
1bc40 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
1bc50 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
1bc60 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
1bc70 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
1bc80 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
1bc90 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
1bca0 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69  oc() and the pri
1bcb0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
1bcc0 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73   freed..** ^If s
1bcd0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1bce0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74   returns NULL, t
1bcf0 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c  hen the prior al
1bd00 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e  location.** is n
1bd10 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
1bd20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75  ^The memory retu
1bd30 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1bd40 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c  malloc() and sql
1bd50 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a  ite3_realloc().*
1bd60 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67  * is always alig
1bd70 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20  ned to at least 
1bd80 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61  an 8 byte bounda
1bd90 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34  ry, or to a.** 4
1bda0 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69   byte boundary i
1bdb0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f  f the [SQLITE_4_
1bdc0 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c  BYTE_ALIGNED_MAL
1bdd0 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  LOC] compile-tim
1bde0 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75  e.** option is u
1bdf0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  sed..**.** In SQ
1be00 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
1be10 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
1be20 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
1be30 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
1be40 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
1be50 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
1be60 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
1be70 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
1be80 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1be90 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
1bea0 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
1beb0 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
1bec0 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
1bed0 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
1bee0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
1bef0 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
1bf00 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72  e used..**.** Pr
1bf10 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65  ior to SQLite ve
1bf20 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68  rsion 3.7.10, th
1bf30 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
1bf40 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
1bf50 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  led.** the syste
1bf60 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
1bf70 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
1bf80 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
1bf90 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
1bfa0 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
1bfb0 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
1bfc0 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
1bfd0 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
1bfe0 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
1bff0 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
1c000 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
1c010 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
1c020 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
1c030 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74  rors were detect
1c040 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
1c050 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61  were reported ba
1c060 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
1c070 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
1c080 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
1c090 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1c0a0 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54  _NOMEM]..**.** T
1c0b0 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
1c0c0 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
1c0d0 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
1c0e0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1c0f0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
1c100 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
1c110 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
1c120 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
1c130 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  * invocation of 
1c140 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1c150 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
1c160 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
1c170 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62  ave.** not yet b
1c180 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
1c190 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
1c1a0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
1c1b0 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
1c1c0 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63  art of.** a bloc
1c1d0 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
1c1e0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
1c1f0 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
1c200 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1c210 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1c220 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64  lloc()]..*/.void
1c230 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
1c240 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  (int);.void *sql
1c250 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
1c260 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  d*, int);.void s
1c270 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
1c280 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1c290 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
1c2a0 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73  cator Statistics
1c2b0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72  .**.** SQLite pr
1c2c0 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f  ovides these two
1c2d0 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20   interfaces for 
1c2e0 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65  reporting on the
1c2f0 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68   status.** of th
1c300 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
1c310 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  c()], [sqlite3_f
1c320 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ree()], and [sql
1c330 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1c340 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69  ** routines, whi
1c350 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c  ch form the buil
1c360 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
1c370 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
1c380 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
1c390 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1c3a0 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  d()] routine ret
1c3b0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
1c3c0 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d  of bytes.** of m
1c3d0 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20  emory currently 
1c3e0 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c  outstanding (mal
1c3f0 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72  loced but not fr
1c400 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73  eed)..** ^The [s
1c410 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1c420 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69  ghwater()] routi
1c430 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d  ne returns the m
1c440 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20  aximum.** value 
1c450 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  of [sqlite3_memo
1c460 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65  ry_used()] since
1c470 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
1c480 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74  mark.** was last
1c490 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61   reset.  ^The va
1c4a0 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
1c4b0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1c4c0 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
1c4d0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1c4e0 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63  highwater()] inc
1c4f0 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61  lude any overhea
1c500 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51  d.** added by SQ
1c510 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c  Lite in its impl
1c520 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73  ementation of [s
1c530 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1c540 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65  ,.** but not ove
1c550 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74  rhead added by t
1c560 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e  he any underlyin
1c570 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79  g system library
1c580 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61  .** routines tha
1c590 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  t [sqlite3_mallo
1c5a0 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a  c()] may call..*
1c5b0 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
1c5c0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1c5d0 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65   is reset to the
1c5e0 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
1c5f0 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  f.** [sqlite3_me
1c600 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20  mory_used()] if 
1c610 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
1c620 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
1c630 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1c640 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20  highwater()] is 
1c650 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75  true.  ^The valu
1c660 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  e returned.** by
1c670 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1c680 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69  _highwater(1)] i
1c690 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  s the high-water
1c6a0 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74   mark.** prior t
1c6b0 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a  o the reset..*/.
1c6c0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
1c6d0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1c6e0 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33  d(void);.sqlite3
1c6f0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
1c700 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1c710 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a  int resetFlag);.
1c720 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c730 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e   Pseudo-Random N
1c740 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a  umber Generator.
1c750 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e  **.** SQLite con
1c760 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61  tains a high-qua
1c770 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64  lity pseudo-rand
1c780 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61  om number genera
1c790 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20  tor (PRNG) used 
1c7a0 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e  to.** select ran
1c7b0 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57  dom [ROWID | ROW
1c7c0 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74  IDs] when insert
1c7d0 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20  ing new records 
1c7e0 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61  into a table tha
1c7f0 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65  t.** already use
1c800 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f  s the largest po
1c810 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20  ssible [ROWID]. 
1c820 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73   The PRNG is als
1c830 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68  o used for.** th
1c840 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f  e build-in rando
1c850 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c  m() and randombl
1c860 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  ob() SQL functio
1c870 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66  ns.  This interf
1c880 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70  ace allows.** ap
1c890 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63  plications to ac
1c8a0 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52  cess the same PR
1c8b0 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72  NG for other pur
1c8c0 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  poses..**.** ^A 
1c8d0 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
1c8e0 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79  tine stores N by
1c8f0 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
1c900 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e  s into buffer P.
1c910 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
1c920 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74  t time this rout
1c930 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  ine is invoked (
1c940 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c  either internall
1c950 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61  y or by.** the a
1c960 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20  pplication) the 
1c970 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75  PRNG is seeded u
1c980 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20  sing randomness 
1c990 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
1c9a0 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   the xRandomness
1c9b0 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64   method of the d
1c9c0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
1c9d0 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  vfs] object..** 
1c9e0 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65  ^On all subseque
1c9f0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20  nt invocations, 
1ca00 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  the pseudo-rando
1ca10 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74  mness is generat
1ca20 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79  ed.** internally
1ca30 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63   and without rec
1ca40 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71  ourse to the [sq
1ca50 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64  lite3_vfs] xRand
1ca60 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64  omness.** method
1ca70 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
1ca80 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74  3_randomness(int
1ca90 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f   N, void *P);../
1caa0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1cab0 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68  ompile-Time Auth
1cac0 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61  orization Callba
1cad0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  cks.**.** ^This 
1cae0 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72  routine register
1caf0 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  s an authorizer 
1cb00 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20  callback with a 
1cb10 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
1cb20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1cb30 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e  on], supplied in
1cb40 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
1cb50 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74  ent..** ^The aut
1cb60 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1cb70 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53   is invoked as S
1cb80 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
1cb90 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64  e being compiled
1cba0 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
1cbb0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
1cbc0 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69  s variants [sqli
1cbd0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1cbe0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
1cbf0 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20  repare16()] and 
1cc00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1cc10 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76  16_v2()].  ^At v
1cc20 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73  arious.** points
1cc30 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
1cc40 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c  ilation process,
1cc50 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69   as logic is bei
1cc60 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f  ng created.** to
1cc70 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
1cc80 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75   actions, the au
1cc90 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1cca0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a  k is invoked to.
1ccb0 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20  ** see if those 
1ccc0 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f  actions are allo
1ccd0 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f  wed.  ^The autho
1cce0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73  rizer callback s
1ccf0 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
1cd00 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61  [SQLITE_OK] to a
1cd10 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c  llow the action,
1cd20 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1cd30 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65   to disallow the
1cd40 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74  .** specific act
1cd50 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68  ion but allow th
1cd60 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1cd70 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  to continue to b
1cd80 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f  e.** compiled, o
1cd90 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
1cda0 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  to cause the ent
1cdb0 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ire SQL statemen
1cdc0 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63  t to be.** rejec
1cdd0 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ted with an erro
1cde0 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68  r.  ^If the auth
1cdf0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1ce00 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76  returns.** any v
1ce10 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20  alue other than 
1ce20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
1ce30 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72   [SQLITE_OK], or
1ce40 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a   [SQLITE_DENY].*
1ce50 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69  * then the [sqli
1ce60 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1ce70 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
1ce80 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
1ce90 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  red.** the autho
1cea0 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
1ceb0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
1cec0 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ssage..**.** Whe
1ced0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
1cee0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
1cef0 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  K], that means t
1cf00 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
1cf10 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e  requested is ok.
1cf20 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c    ^When the call
1cf30 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1cf40 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
1cf50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1cf60 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
1cf70 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
1cf80 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a  t triggered the.
1cf90 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  ** authorizer wi
1cfa0 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
1cfb0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
1cfc0 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
1cfd0 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
1cfe0 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  d. .**.** ^The f
1cff0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1d000 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
1d010 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
1d020 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
1d030 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
1d040 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
1d050 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e  _authorizer() in
1d060 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65  terface. ^The se
1d070 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  cond parameter.*
1d080 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
1d090 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
1d0a0 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
1d0b0 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
1d0c0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
1d0d0 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
1d0e0 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1d0f0 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64  ized. ^The third
1d100 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
1d110 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
1d120 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
1d130 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1d140 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
1d150 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c  ntain additional
1d160 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75  .** details abou
1d170 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
1d180 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
1d190 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  *.** ^If the act
1d1a0 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
1d1b0 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64  ITE_READ].** and
1d1c0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1d1d0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47  turns [SQLITE_IG
1d1e0 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a  NORE] then the.*
1d1f0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
1d200 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74  ement] statement
1d210 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20   is constructed 
1d220 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a  to substitute.**
1d230 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
1d240 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
1d250 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
1d260 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65  would have.** be
1d270 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
1d280 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
1d290 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b  returned.  The [
1d2a0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a  SQLITE_IGNORE].*
1d2b0 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20  * return can be 
1d2c0 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20  used to deny an 
1d2d0 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61  untrusted user a
1d2e0 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64  ccess to individ
1d2f0 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f  ual.** columns o
1d300 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49  f a table..** ^I
1d310 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
1d320 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c  e is [SQLITE_DEL
1d330 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c  ETE] and the cal
1d340 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
1d350 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1d360 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54   then the [DELET
1d370 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f  E] operation pro
1d380 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a  ceeds but the.**
1d390 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d   [truncate optim
1d3a0 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61  ization] is disa
1d3b0 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77  bled and all row
1d3c0 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e  s are deleted in
1d3d0 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a  dividually..**.*
1d3e0 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  * An authorizer 
1d3f0 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71  is used when [sq
1d400 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
1d410 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51  preparing].** SQ
1d420 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f  L statements fro
1d430 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  m an untrusted s
1d440 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65  ource, to ensure
1d450 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74   that the SQL st
1d460 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e  atements.** do n
1d470 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73  ot try to access
1d480 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e   data they are n
1d490 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65  ot allowed to se
1d4a0 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20  e, or that they 
1d4b0 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f  do not.** try to
1d4c0 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f   execute malicio
1d4d0 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  us statements th
1d4e0 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61  at damage the da
1d4f0 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20  tabase.  For.** 
1d500 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
1d510 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f  ication may allo
1d520 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65  w a user to ente
1d530 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53  r arbitrary.** S
1d540 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65  QL queries for e
1d550 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64  valuation by a d
1d560 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68  atabase.  But th
1d570 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
1d580 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
1d590 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62  he user to be ab
1d5a0 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74  le to make arbit
1d5b0 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20  rary changes to 
1d5c0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
1d5d0 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20    An authorizer 
1d5e0 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75  could then be pu
1d5f0 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65  t in place while
1d600 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74   the.** user-ent
1d610 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e  ered SQL is bein
1d620 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
1d630 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74  re | prepared] t
1d640 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73  hat.** disallows
1d650 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65   everything exce
1d660 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  pt [SELECT] stat
1d670 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70  ements..**.** Ap
1d680 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
1d690 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20  need to process 
1d6a0 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74  SQL from untrust
1d6b0 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69  ed sources.** mi
1d6c0 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65  ght also conside
1d6d0 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75  r lowering resou
1d6e0 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67  rce limits using
1d6f0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1d700 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69  )].** and limiti
1d710 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65  ng database size
1d720 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f   using the [max_
1d730 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
1d740 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74  GMA].** in addit
1d750 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20  ion to using an 
1d760 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a  authorizer..**.*
1d770 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  * ^(Only a singl
1d780 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e  e authorizer can
1d790 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20   be in place on 
1d7a0 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
1d7b0 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69  ction.** at a ti
1d7c0 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74  me.  Each call t
1d7d0 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
1d7e0 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64  thorizer overrid
1d7f0 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f  es the.** previo
1d800 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73  us call.)^  ^Dis
1d810 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69  able the authori
1d820 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e  zer by installin
1d830 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63  g a NULL callbac
1d840 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  k..** The author
1d850 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
1d860 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
1d870 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
1d880 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
1d890 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
1d8a0 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
1d8b0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1d8c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1d8d0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74   invoked the aut
1d8e0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1d8f0 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
1d900 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1d910 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
1d920 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
1d930 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
1d940 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d950 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
1d960 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
1d970 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
1d980 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  ph..**.** ^When 
1d990 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1d9a0 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74  _v2()] is used t
1d9b0 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74  o prepare a stat
1d9c0 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74  ement, the.** st
1d9d0 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65  atement might be
1d9e0 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72   re-prepared dur
1d9f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
1da00 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a  p()] due to a .*
1da10 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  * schema change.
1da20 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70    Hence, the app
1da30 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
1da40 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  ensure that the.
1da50 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f  ** correct autho
1da60 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
1da70 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20  emains in place 
1da80 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69  during the [sqli
1da90 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
1daa0 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  ** ^Note that th
1dab0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1dac0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1dad0 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20   only during.** 
1dae0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1daf0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1db00 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74  nts.  Authorizat
1db10 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65  ion is not.** pe
1db20 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73  rformed during s
1db30 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74  tatement evaluat
1db40 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ion in [sqlite3_
1db50 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a  step()], unless.
1db60 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20  ** as stated in 
1db70 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
1db80 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f  agraph, sqlite3_
1db90 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a  step() invokes.*
1dba0 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
1dbb0 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70  e_v2() to reprep
1dbc0 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20  are a statement 
1dbd0 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63  after a schema c
1dbe0 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  hange..*/.int sq
1dbf0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1dc00 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a  izer(.  sqlite3*
1dc10 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29  ,.  int (*xAuth)
1dc20 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
1dc30 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
1dc40 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
1dc50 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76  onst char*),.  v
1dc60 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29  oid *pUserData.)
1dc70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1dc80 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65  F: Authorizer Re
1dc90 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  turn Codes.**.**
1dca0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
1dcb0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1dcc0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1dcd0 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
1dce0 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
1dcf0 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
1dd00 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
1dd10 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
1dd20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
1dd30 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
1dd40 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
1dd50 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
1dd60 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
1dd70 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1dd80 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
1dd90 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
1dda0 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
1ddb0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
1ddc0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
1ddd0 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69   SQLITE_IGNORE i
1dde0 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61  s also used as a
1ddf0 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43   [SQLITE_ROLLBAC
1de00 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f 64 65 5d  K | return code]
1de10 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  .** from the [sq
1de20 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f  lite3_vtab_on_co
1de30 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66  nflict()] interf
1de40 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ace..*/.#define 
1de50 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20  SQLITE_DENY   1 
1de60 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53    /* Abort the S
1de70 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  QL statement wit
1de80 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64  h an error */.#d
1de90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e  efine SQLITE_IGN
1dea0 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74  ORE 2   /* Don't
1deb0 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62   allow access, b
1dec0 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74  ut don't generat
1ded0 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f  e an error */../
1dee0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
1def0 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e  uthorizer Action
1df00 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
1df10 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1df20 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65  thorizer()] inte
1df30 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
1df40 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
1df50 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ion.** that is i
1df60 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72  nvoked to author
1df70 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20  ize certain SQL 
1df80 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e  statement action
1df90 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  s.  The.** secon
1dfa0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
1dfb0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
1dfc0 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74  n integer code t
1dfd0 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
1dfe0 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20   what action is 
1dff0 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64  being authorized
1e000 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65  .  These are the
1e010 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20   integer action 
1e020 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  codes that.** th
1e030 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1e040 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73  lback may be pas
1e050 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  sed..**.** These
1e060 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c   action code val
1e070 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74  ues signify what
1e080 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69   kind of operati
1e090 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61  on is to be.** a
1e0a0 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20  uthorized.  The 
1e0b0 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61  3rd and 4th para
1e0c0 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75  meters to the au
1e0d0 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63  thorization.** c
1e0e0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1e0f0 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74   will be paramet
1e100 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65  ers or NULL depe
1e110 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f  nding on which o
1e120 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73  f these.** codes
1e130 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
1e140 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1e150 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72  .  ^(The 5th par
1e160 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
1e170 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1e180 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65  back is the name
1e190 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
1e1a0 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22   ("main", "temp"
1e1b0 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70  ,.** etc.) if ap
1e1c0 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68  plicable.)^  ^Th
1e1d0 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 6th parameter 
1e1e0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
1e1f0 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  r callback.** is
1e200 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1e210 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67   inner-most trig
1e220 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74  ger or view that
1e230 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
1e240 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73  for.** the acces
1e250 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c  s attempt or NUL
1e260 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73  L if this access
1e270 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65   attempt is dire
1e280 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70  ctly from.** top
1e290 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e  -level SQL code.
1e2a0 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .*/./***********
1e2b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e2c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e2d0 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   3rd ***********
1e2e0 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 4th **********
1e2f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e300 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20  E_CREATE_INDEX  
1e310 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49          1   /* I
1e320 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1e330 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1e340 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e350 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20  _CREATE_TABLE   
1e360 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61         2   /* Ta
1e370 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1e380 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1e390 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e3a0 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45  CREATE_TEMP_INDE
1e3b0 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64  X     3   /* Ind
1e3c0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1e3d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1e3e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1e3f0 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45  REATE_TEMP_TABLE
1e400 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c       4   /* Tabl
1e410 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1e420 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1e430 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1e440 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45  EATE_TEMP_TRIGGE
1e450 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67  R   5   /* Trigg
1e460 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1e470 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1e480 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1e490 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ATE_TEMP_VIEW   
1e4a0 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e     6   /* View N
1e4b0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1e4c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1e4d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1e4e0 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  TE_TRIGGER      
1e4f0 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72    7   /* Trigger
1e500 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1e510 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1e520 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1e530 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  E_VIEW          
1e540 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   8   /* View Nam
1e550 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1e560 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1e570 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  ne SQLITE_DELETE
1e580 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1e590 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
1e5a0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1e5b0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1e5c0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e  e SQLITE_DROP_IN
1e5d0 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30  DEX           10
1e5e0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1e5f0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1e600 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1e610 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42   SQLITE_DROP_TAB
1e620 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20  LE           11 
1e630 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1e640 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1e650 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e660 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
1e670 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20  _INDEX      12  
1e680 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1e690 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1e6a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e6b0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
1e6c0 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20  TABLE      13   
1e6d0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1e6e0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1e6f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e700 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
1e710 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f  RIGGER    14   /
1e720 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1e730 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1e740 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e750 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49  ITE_DROP_TEMP_VI
1e760 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a  EW       15   /*
1e770 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1e780 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1e790 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e7a0 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20  TE_DROP_TRIGGER 
1e7b0 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20          16   /* 
1e7c0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1e7d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1e7e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e7f0 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20  E_DROP_VIEW     
1e800 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56         17   /* V
1e810 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1e820 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1e830 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e840 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20  _INSERT         
1e850 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61        18   /* Ta
1e860 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1e870 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1e880 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e890 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
1e8a0 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61       19   /* Pra
1e8b0 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74  gma Name     1st
1e8c0 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a   arg or NULL */.
1e8d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
1e8e0 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
1e8f0 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c      20   /* Tabl
1e900 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
1e910 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
1e920 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
1e930 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20  LECT            
1e940 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     21   /* NULL 
1e950 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
1e960 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1e970 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
1e980 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20  NSACTION        
1e990 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    22   /* Operat
1e9a0 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ion       NULL  
1e9b0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1e9c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41  fine SQLITE_UPDA
1e9d0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
1e9e0 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   23   /* Table N
1e9f0 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
1ea00 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1ea10 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43  ine SQLITE_ATTAC
1ea20 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
1ea30 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65  24   /* Filename
1ea40 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
1ea50 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1ea60 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48  ne SQLITE_DETACH
1ea70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1ea80 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
1ea90 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20  Name   NULL     
1eaa0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1eab0 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54  e SQLITE_ALTER_T
1eac0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36  ABLE          26
1ead0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
1eae0 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  ame   Table Name
1eaf0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1eb00 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20   SQLITE_REINDEX 
1eb10 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20               27 
1eb20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1eb30 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1eb40 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1eb50 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20  SQLITE_ANALYZE  
1eb60 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20              28  
1eb70 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1eb80 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1eb90 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1eba0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41  QLITE_CREATE_VTA
1ebb0 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20  BLE        29   
1ebc0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1ebd0 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
1ebe0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ebf0 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45  LITE_DROP_VTABLE
1ec00 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f            30   /
1ec10 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1ec20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
1ec30 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ec40 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  ITE_FUNCTION    
1ec50 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a           31   /*
1ec60 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1ec70 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20   Function Name  
1ec80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ec90 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20  TE_SAVEPOINT    
1eca0 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20          32   /* 
1ecb0 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
1ecc0 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20  Savepoint Name  
1ecd0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ece0 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20  E_COPY          
1ecf0 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e          0   /* N
1ed00 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f  o longer used */
1ed10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ed20 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72  : Tracing And Pr
1ed30 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e  ofiling Function
1ed40 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
1ed50 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20  utines register 
1ed60 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1ed70 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75  ns that can be u
1ed80 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69  sed for.** traci
1ed90 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67  ng and profiling
1eda0 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
1edb0 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  f SQL statements
1edc0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
1edd0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
1ede0 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
1edf0 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20  ite3_trace() is 
1ee00 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61  invoked at.** va
1ee10 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e  rious times when
1ee20 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1ee30 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62  t is being run b
1ee40 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  y [sqlite3_step(
1ee50 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  )]..** ^The sqli
1ee60 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
1ee70 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1ee80 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e  with a UTF-8 ren
1ee90 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a  dering of the.**
1eea0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1eeb0 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65  ext as the state
1eec0 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e  ment first begin
1eed0 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20  s executing..** 
1eee0 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c  ^(Additional sql
1eef0 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
1ef00 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63  lbacks might occ
1ef10 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72  ur.** as each tr
1ef20 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72  iggered subprogr
1ef30 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20  am is entered.  
1ef40 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f  The callbacks fo
1ef50 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f  r triggers.** co
1ef60 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51  ntain a UTF-8 SQ
1ef70 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69  L comment that i
1ef80 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72  dentifies the tr
1ef90 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  igger.)^.**.** T
1efa0 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  he [SQLITE_TRACE
1efb0 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d  _SIZE_LIMIT] com
1efc0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1efd0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1efe0 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e  limit.** the len
1eff0 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61  gth of [bound pa
1f000 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69  rameter] expansi
1f010 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74  on in the output
1f020 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63   of sqlite3_trac
1f030 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e()..**.** ^The 
1f040 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1f050 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
1f060 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
1f070 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
1f080 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  as each SQL stat
1f090 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20  ement finishes. 
1f0a0 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
1f0b0 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
1f0c0 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
1f0d0 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
1f0e0 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
1f0f0 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
1f100 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
1f110 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
1f120 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54  took to run.  ^T
1f130 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
1f140 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69  ack.** time is i
1f150 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73  n units of nanos
1f160 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20  econds, however 
1f170 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
1f180 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73  ementation.** is
1f190 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66   only capable of
1f1a0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73   millisecond res
1f1b0 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73  olution so the s
1f1c0 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69  ix least signifi
1f1d0 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69  cant.** digits i
1f1e0 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d  n the time are m
1f1f0 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74  eaningless.  Fut
1f200 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1f210 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20  SQLite.** might 
1f220 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20  provide greater 
1f230 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68  resolution on th
1f240 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62  e profiler callb
1f250 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ack.  The.** sql
1f260 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66  ite3_profile() f
1f270 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69  unction is consi
1f280 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74  dered experiment
1f290 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62  al and is.** sub
1f2a0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69  ject to change i
1f2b0 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
1f2c0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
1f2d0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72  void *sqlite3_tr
1f2e0 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ace(sqlite3*, vo
1f2f0 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
1f300 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
1f310 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45  void*);.SQLITE_E
1f320 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64  XPERIMENTAL void
1f330 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   *sqlite3_profil
1f340 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
1f350 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76  oid(*xProfile)(v
1f360 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
1f370 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  ,sqlite3_uint64)
1f380 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
1f390 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
1f3a0 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
1f3b0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
1f3c0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
1f3d0 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29  handler(D,N,X,P)
1f3e0 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
1f3f0 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  s the callback.*
1f400 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20  * function X to 
1f410 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  be invoked perio
1f420 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
1f430 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  ong running call
1f440 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
1f450 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
1f460 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b  e3_step()] and [
1f470 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1f480 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61  e()] for.** data
1f490 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1f4a0 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  D.  An example u
1f4b0 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
1f4c0 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
1f4d0 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
1f4e0 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
1f4f0 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54   query..**.** ^T
1f500 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  he parameter P i
1f510 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
1f520 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
1f530 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a  ameter to the .*
1f540 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
1f550 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72  ion X.  ^The par
1f560 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20  ameter N is the 
1f570 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62  approximate numb
1f580 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75  er of .** [virtu
1f590 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72  al machine instr
1f5a0 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72  uctions] that ar
1f5b0 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77  e evaluated betw
1f5c0 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a  een successive.*
1f5d0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
1f5e0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e   the callback X.
1f5f0 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20    ^If N is less 
1f600 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68  than one then th
1f610 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61  e progress.** ha
1f620 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65  ndler is disable
1f630 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61  d..**.** ^Only a
1f640 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73   single progress
1f650 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20   handler may be 
1f660 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74  defined at one t
1f670 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61  ime per.** [data
1f680 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1f690 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20  ; setting a new 
1f6a0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1f6b0 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20   cancels the.** 
1f6c0 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69  old one.  ^Setti
1f6d0 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74  ng parameter X t
1f6e0 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20  o NULL disables 
1f6f0 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
1f700 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72  dler..** ^The pr
1f710 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69  ogress handler i
1f720 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20  s also disabled 
1f730 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20  by setting N to 
1f740 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20  a value less.** 
1f750 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49  than 1..**.** ^I
1f760 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
1f770 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1f780 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
1f790 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  eration is.** in
1f7a0 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
1f7b0 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
1f7c0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
1f7d0 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
1f7e0 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
1f7f0 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20  progress dialog 
1f800 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  box..**.** The p
1f810 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1f820 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
1f830 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
1f840 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
1f850 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
1f860 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
1f870 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72  nvoked the progr
1f880 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
1f890 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
1f8a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1f8b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
1f8c0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
1f8d0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
1f8e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
1f8f0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
1f900 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
1f910 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
1f920 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  *.*/.void sqlite
1f930 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1f940 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
1f950 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
1f960 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
1f970 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e  CAPI3REF: Openin
1f980 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65  g A New Database
1f990 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a   Connection.**.*
1f9a0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
1f9b0 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65  s open an SQLite
1f9c0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61   database file a
1f9d0 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  s specified by t
1f9e0 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  he .** filename 
1f9f0 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66  argument. ^The f
1fa00 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1fa10 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
1fa20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  as UTF-8 for.** 
1fa30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1fa40 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
1fa50 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d  v2() and as UTF-
1fa60 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
1fa70 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66   byte.** order f
1fa80 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  or sqlite3_open1
1fa90 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61  6(). ^(A [databa
1faa0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
1fab0 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
1fac0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
1fad0 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
1fae0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
1faf0 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
1fb00 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
1fb10 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
1fb20 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
1fb30 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
1fb40 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
1fb50 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
1fb60 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
1fb70 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
1fb80 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
1fb90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
1fba0 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66  * object.)^ ^(If
1fbb0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
1fbc0 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20   opened (and/or 
1fbd0 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73  created) success
1fbe0 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b  fully, then.** [
1fbf0 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
1fc00 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
1fc10 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
1fc20 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  e] is returned.)
1fc30 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ^ ^The.** [sqlit
1fc40 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20  e3_errmsg()] or 
1fc50 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
1fc60 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61  6()] routines ca
1fc70 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
1fc80 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73  ain.** an Englis
1fc90 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72  h language descr
1fca0 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72  iption of the er
1fcb0 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ror following a 
1fcc0 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a  failure of any.*
1fcd0 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
1fce0 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73  _open() routines
1fcf0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
1fd00 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  ault encoding fo
1fd10 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77  r the database w
1fd20 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a  ill be UTF-8 if.
1fd30 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
1fd40 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
1fd50 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  n_v2() is called
1fd60 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69   and.** UTF-16 i
1fd70 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
1fd80 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74  e order if sqlit
1fd90 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75  e3_open16() is u
1fda0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  sed..**.** Wheth
1fdb0 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
1fdc0 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
1fdd0 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
1fde0 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
1fdf0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
1fe00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1fe10 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c  on] handle shoul
1fe20 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  d be released by
1fe30 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74  .** passing it t
1fe40 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
1fe50 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e  ()] when it is n
1fe60 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65  o longer require
1fe70 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
1fe80 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1fe90 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
1fea0 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ike sqlite3_open
1feb0 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
1fec0 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f  t it accepts two
1fed0 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
1fee0 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
1fef0 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ional control.**
1ff00 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61   over the new da
1ff10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ff20 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20  n.  ^(The flags 
1ff30 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
1ff40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1ff50 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f  ) can take one o
1ff60 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
1ff70 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c  ng three values,
1ff80 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
1ff90 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ined with the .*
1ffa0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  * [SQLITE_OPEN_N
1ffb0 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  OMUTEX], [SQLITE
1ffc0 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
1ffd0 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  , [SQLITE_OPEN_S
1ffe0 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20  HAREDCACHE],.** 
1fff0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
20000 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f  VATECACHE], and/
20010 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
20020 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a  URI] flags:)^.**
20030 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64  .** <dl>.** ^(<d
20040 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
20050 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a  EADONLY]</dt>.**
20060 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
20070 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72  e is opened in r
20080 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20  ead-only mode.  
20090 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
200a0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65  does not.** alre
200b0 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72  ady exist, an er
200c0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
200d0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
200e0 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
200f0 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e  _READWRITE]</dt>
20100 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
20110 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
20120 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
20130 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
20140 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a  le, or reading.*
20150 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69  * only if the fi
20160 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
20170 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
20180 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
20190 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73  In either.** cas
201a0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d  e the database m
201b0 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  ust already exis
201c0 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  t, otherwise an 
201d0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
201e0 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
201f0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
20200 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
20210 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
20220 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATE]</dt>.** <dd
20230 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
20240 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
20250 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c  ing and writing,
20260 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20   and is created 
20270 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f  if.** it does no
20280 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
20290 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68   This is the beh
202a0 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c  avior that is al
202b0 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a  ways used for.**
202c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
202d0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
202e0 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  16().</dd>)^.** 
202f0 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  </dl>.**.** If t
20300 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
20310 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
20320 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  _v2() is not one
20330 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69   of the.** combi
20340 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
20350 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  ove optionally c
20360 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68  ombined with oth
20370 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  er.** [SQLITE_OP
20380 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51  EN_READONLY | SQ
20390 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73  LITE_OPEN_* bits
203a0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65  ].** then the be
203b0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
203c0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ned..**.** ^If t
203d0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
203e0 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  NOMUTEX] flag is
203f0 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64   set, then the d
20400 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20410 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74  on.** opens in t
20420 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20  he multi-thread 
20430 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
20440 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
20450 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a  single-thread.**
20460 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65   mode has not be
20470 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  en set at compil
20480 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
20490 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a  time.  ^If the.*
204a0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  * [SQLITE_OPEN_F
204b0 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  ULLMUTEX] flag i
204c0 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64  s set then the d
204d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
204e0 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74  on opens.** in t
204f0 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
20500 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75  hreading mode] u
20510 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72  nless single-thr
20520 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  ead was.** previ
20530 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61  ously selected a
20540 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
20550 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a  r start-time..**
20560 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
20570 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20  EN_SHAREDCACHE] 
20580 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
20590 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
205a0 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69  ion to be.** eli
205b0 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68  gible to use [sh
205c0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
205d0 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  , regardless of 
205e0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
205f0 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69  hared.** cache i
20600 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20  s enabled using 
20610 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
20620 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e  shared_cache()].
20630 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54    ^The.** [SQLIT
20640 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
20650 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
20660 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
20670 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a  nnection to not.
20680 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69  ** participate i
20690 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  n [shared cache 
206a0 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74  mode] even if it
206b0 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
206c0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
206d0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
206e0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
206f0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
20700 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
20710 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
20720 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74  fines the operat
20730 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
20740 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  face that.** the
20750 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
20760 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  nnection should 
20770 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f  use.  ^If the fo
20780 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
20790 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
207a0 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66  ter then the def
207b0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
207c0 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  s] object is use
207d0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
207e0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d   filename is ":m
207f0 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20  emory:", then a 
20800 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
20810 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  ry in-memory dat
20820 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61  abase.** is crea
20830 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
20840 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69  ection.  ^This i
20850 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
20860 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68  e will vanish wh
20870 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  en.** the databa
20880 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
20890 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
208a0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
208b0 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b  ite might.** mak
208c0 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
208d0 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
208e0 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e  names that begin
208f0 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68   with the ":" ch
20900 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69  aracter..** It i
20910 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
20920 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  at when a databa
20930 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75  se filename actu
20940 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20  ally does begin 
20950 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68  with.** a ":" ch
20960 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75  aracter you shou
20970 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ld prefix the fi
20980 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
20990 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a  thname such as.*
209a0 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20  * "./" to avoid 
209b0 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a  ambiguity..**.**
209c0 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
209d0 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  e is an empty st
209e0 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
209f0 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a  vate, temporary.
20a00 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  ** on-disk datab
20a10 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
20a20 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76  ted.  ^This priv
20a30 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
20a40 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
20a50 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
20a60 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
20a70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20a80 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
20a90 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
20aa0 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65  s in sqlite3_ope
20ab0 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69  n()]] <h3>URI Fi
20ac0 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  lenames</h3>.**.
20ad0 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65  ** ^If [URI file
20ae0 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61  name] interpreta
20af0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c  tion is enabled,
20b00 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d   and the filenam
20b10 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65  e argument.** be
20b20 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a  gins with "file:
20b30 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65  ", then the file
20b40 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65  name is interpre
20b50 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55  ted as a URI. ^U
20b60 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  RI.** filename i
20b70 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
20b80 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
20b90 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
20ba0 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74  ] flag is.** set
20bb0 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61   in the fourth a
20bc0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
20bd0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72  e3_open_v2(), or
20be0 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65   if it has.** be
20bf0 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61  en enabled globa
20c00 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53  lly using the [S
20c10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
20c20 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68  ] option with th
20c30 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
20c40 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f  nfig()] method o
20c50 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  r by the [SQLITE
20c60 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c  _USE_URI] compil
20c70 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a  e-time option..*
20c80 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76  * As of SQLite v
20c90 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52  ersion 3.7.7, UR
20ca0 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  I filename inter
20cb0 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72  pretation is tur
20cc0 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65  ned off.** by de
20cd0 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72  fault, but futur
20ce0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
20cf0 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c  Lite might enabl
20d00 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a  e URI filename.*
20d10 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  * interpretation
20d20 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65   by default.  Se
20d30 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  e "[URI filename
20d40 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  s]" for addition
20d50 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
20d60 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c  n..**.** URI fil
20d70 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65  enames are parse
20d80 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52  d according to R
20d90 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65  FC 3986. ^If the
20da0 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e   URI contains an
20db0 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74  .** authority, t
20dc0 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65  hen it must be e
20dd0 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73  ither an empty s
20de0 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72  tring or the str
20df0 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f  ing .** "localho
20e00 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74  st". ^If the aut
20e10 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e  hority is not an
20e20 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
20e30 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e   "localhost", an
20e40 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65   .** error is re
20e50 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61  turned to the ca
20e60 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d  ller. ^The fragm
20e70 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ent component of
20e80 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70   a URI, if .** p
20e90 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72  resent, is ignor
20ea0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ed..**.** ^SQLit
20eb0 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20  e uses the path 
20ec0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65  component of the
20ed0 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65   URI as the name
20ee0 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c   of the disk fil
20ef0 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61  e.** which conta
20f00 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ins the database
20f10 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62  . ^If the path b
20f20 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27  egins with a '/'
20f30 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20   character, .** 
20f40 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72  then it is inter
20f50 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73  preted as an abs
20f60 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20  olute path. ^If 
20f70 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f  the path does no
20f80 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68  t begin .** with
20f90 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20   a '/' (meaning 
20fa0 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
20fb0 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d  ty section is om
20fc0 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55  itted from the U
20fd0 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  RI).** then the 
20fe0 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65  path is interpre
20ff0 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76  ted as a relativ
21000 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20  e path. .** ^On 
21010 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72  windows, the fir
21020 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  st component of 
21030 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
21040 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20   .** is a drive 
21050 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65  specification (e
21060 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a  .g. "C:")..**.**
21070 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72   [[core URI quer
21080 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a  y parameters]].*
21090 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70  * The query comp
210a0 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d  onent of a URI m
210b0 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d  ay contain param
210c0 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69  eters that are i
210d0 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69  nterpreted.** ei
210e0 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69  ther by SQLite i
210f0 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b  tself, or by a [
21100 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53  VFS | custom VFS
21110 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d   implementation]
21120 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  ..** SQLite inte
21130 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f  rprets the follo
21140 77 69 6e 67 20 74 68 72 65 65 20 71 75 65 72 79  wing three query
21150 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a   parameters:.**.
21160 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
21170 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54  > <b>vfs</b>: ^T
21180 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74  he "vfs" paramet
21190 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74  er may be used t
211a0 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61  o specify the na
211b0 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56  me of.**     a V
211c0 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70  FS object that p
211d0 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72  rovides the oper
211e0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
211f0 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75  erface that shou
21200 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65  ld.**     be use
21210 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  d to access the 
21220 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e  database file on
21230 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20   disk. ^If this 
21240 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
21250 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79  .**     an empty
21260 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61   string the defa
21270 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69  ult VFS object i
21280 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79  s used. ^Specify
21290 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a  ing an unknown.*
212a0 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20  *     VFS is an 
212b0 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74  error. ^If sqlit
212c0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
212d0 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73  used and the vfs
212e0 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
212f0 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20    present, then 
21300 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65  the VFS specifie
21310 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20  d by the option 
21320 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65  takes precedence
21330 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65   over.**     the
21340 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
21350 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
21360 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
21370 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
21380 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65  *   <li> <b>mode
21390 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65  </b>: ^(The mode
213a0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
213b0 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
213c0 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20  "ro", "rw",.**  
213d0 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65     "rwc", or "me
213e0 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e  mory". Attemptin
213f0 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61  g to set it to a
21400 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69  ny other value i
21410 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f  s.**     an erro
21420 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66  r)^. .**     ^If
21430 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69   "ro" is specifi
21440 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  ed, then the dat
21450 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
21460 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a  for read-only .*
21470 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75  *     access, ju
21480 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51  st as if the [SQ
21490 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
214a0 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65  LY] flag had bee
214b0 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a  n set in the .**
214c0 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d       third argum
214d0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ent to sqlite3_o
214e0 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68  pen_v2(). ^If th
214f0 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73  e mode option is
21500 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20   set to .**     
21510 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64  "rw", then the d
21520 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
21530 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65  d for read-write
21540 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65   (but not create
21550 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  ) .**     access
21560 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f  , as if SQLITE_O
21570 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62  PEN_READWRITE (b
21580 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50  ut not SQLITE_OP
21590 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a  EN_CREATE) had .
215a0 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e  **     been set.
215b0 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73   ^Value "rwc" is
215c0 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
215d0 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20  etting both .** 
215e0 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
215f0 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51  READWRITE and SQ
21600 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
21610 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  .  ^If the mode 
21620 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
21630 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22   set to "memory"
21640 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e   then a pure [in
21650 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
21660 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61  ] that never rea
21670 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69  ds.**     or wri
21680 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73  tes from disk is
21690 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e   used. ^It is an
216a0 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66   error to specif
216b0 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a  y a value for.**
216c0 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61       the mode pa
216d0 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20  rameter that is 
216e0 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65  less restrictive
216f0 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69   than that speci
21700 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74  fied by.**     t
21710 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20  he flags passed 
21720 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72  in the third par
21730 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
21740 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
21750 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63  **   <li> <b>cac
21760 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63  he</b>: ^The cac
21770 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
21780 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
21790 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a  r "shared" or.**
217a0 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20       "private". 
217b0 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22  ^Setting it to "
217c0 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76  shared" is equiv
217d0 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
217e0 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49   the.**     SQLI
217f0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
21800 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66  CHE bit in the f
21810 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61  lags argument pa
21820 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73  ssed to.**     s
21830 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
21840 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63  . ^Setting the c
21850 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74  ache parameter t
21860 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a  o "private" is .
21870 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e  **     equivalen
21880 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
21890 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
218a0 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a  VATECACHE bit..*
218b0 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65  *     ^If sqlite
218c0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
218d0 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63  sed and the "cac
218e0 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73  he" parameter is
218f0 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20   present in.**  
21900 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d     a URI filenam
21910 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65  e, its value ove
21920 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76  rrides any behav
21930 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79  ior requested by
21940 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20   setting.**     
21950 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
21960 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49  ATECACHE or SQLI
21970 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
21980 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75  CHE flag..** </u
21990 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66  l>.**.** ^Specif
219a0 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20  ying an unknown 
219b0 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
219c0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
219d0 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74   of a URI is not
219e0 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46   an.** error.  F
219f0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
21a00 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75  f SQLite might u
21a10 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69  nderstand additi
21a20 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61  onal query.** pa
21a30 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22  rameters.  See "
21a40 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72  [query parameter
21a50 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d  s with special m
21a60 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65  eaning to SQLite
21a70 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  ]" for.** additi
21a80 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
21a90 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
21aa0 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d  lename examples]
21ab0 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61  ] <h3>URI filena
21ac0 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e  me examples</h3>
21ad0 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  .**.** <table bo
21ae0 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63  rder="1" align=c
21af0 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e  enter cellpaddin
21b00 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  g=5>.** <tr><th>
21b10 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c   URI filenames <
21b20 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c  th> Results.** <
21b30 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
21b40 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
21b50 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
21b60 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
21b70 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
21b80 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e  rectory..** <tr>
21b90 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
21ba0 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e  fred/data.db<br>
21bb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
21bc0 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  e:///home/fred/d
21bd0 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20  ata.db <br> .** 
21be0 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
21bf0 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66  localhost/home/f
21c00 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
21c10 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
21c20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61     Open the data
21c30 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65  base file "/home
21c40 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a  /fred/data.db"..
21c50 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
21c60 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65  ://darkstar/home
21c70 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74  /fred/data.db <t
21c80 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
21c90 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73  An error. "darks
21ca0 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65  tar" is not a re
21cb0 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69  cognized authori
21cc0 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73  ty..** <tr><td s
21cd0 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63  tyle="white-spac
21ce0 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20  e:nowrap"> .**  
21cf0 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
21d00 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61  C:/Documents%20a
21d10 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72  nd%20Settings/fr
21d20 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e  ed/Desktop/data.
21d30 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57  db.**     <td> W
21d40 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65  indows only: Ope
21d50 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
21d60 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64  .db" on fred's d
21d70 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a  esktop on drive.
21d80 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20  **          C:. 
21d90 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32  Note that the %2
21da0 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68  0 escaping in th
21db0 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f  is example is no
21dc0 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20  t strictly .**  
21dd0 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72          necessar
21de0 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63  y - space charac
21df0 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  ters can be used
21e00 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20   literally.**   
21e10 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69         in URI fi
21e20 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e  lenames..** <tr>
21e30 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
21e40 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d  b?mode=ro&cache=
21e50 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a  private <td> .**
21e60 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
21e70 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
21e80 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
21e90 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d  ectory for read-
21ea0 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20  only access..** 
21eb0 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c           Regardl
21ec0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
21ed0 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63  r not shared-cac
21ee0 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c  he mode is enabl
21ef0 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
21f00 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61    default, use a
21f10 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a   private cache..
21f20 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
21f30 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
21f40 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c  .db?vfs=unix-nol
21f50 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20  ock <td>.**     
21f60 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
21f70 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
21f80 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65  db". Use the spe
21f90 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e  cial VFS "unix-n
21fa0 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c  olock"..** <tr><
21fb0 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
21fc0 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c  ?mode=readonly <
21fd0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
21fe0 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64   An error. "read
21ff0 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76  only" is not a v
22000 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20  alid option for 
22010 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d  the "mode" param
22020 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eter..** </table
22030 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78  >.**.** ^URI hex
22040 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
22050 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20  sequences (%HH) 
22060 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69  are supported wi
22070 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e  thin the path an
22080 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f  d.** query compo
22090 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20  nents of a URI. 
220a0 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  A hexadecimal es
220b0 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f  cape sequence co
220c0 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70  nsists of a.** p
220d0 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25  ercent sign - "%
220e0 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  " - followed by 
220f0 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61  exactly two hexa
22100 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a  decimal digits .
22110 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e  ** specifying an
22120 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42   octet value. ^B
22130 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f  efore the path o
22140 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  r query componen
22150 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66  ts of a.** URI f
22160 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65  ilename are inte
22170 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72  rpreted, they ar
22180 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  e encoded using 
22190 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a  UTF-8 and all .*
221a0 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  * hexadecimal es
221b0 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72  cape sequences r
221c0 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e  eplaced by a sin
221d0 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e  gle byte contain
221e0 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  ing the.** corre
221f0 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20  sponding octet. 
22200 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  If this process 
22210 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76  generates an inv
22220 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64  alid UTF-8 encod
22230 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75  ing,.** the resu
22240 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
22250 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
22260 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72   to Windows user
22270 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
22280 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
22290 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
222a0 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ent.** of sqlite
222b0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
222c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d  ite3_open_v2() m
222d0 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
222e0 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f  t whatever.** co
222f0 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
22300 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69  tly defined.  Fi
22310 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
22320 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
22330 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d  .** characters m
22340 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
22350 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
22360 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
22370 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
22380 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
22390 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
223a0 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
223b0 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73  ndows Runtime us
223c0 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65  ers:</b>  The te
223d0 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72  mporary director
223e0 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a  y must be set.**
223f0 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
22400 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  g sqlite3_open()
22410 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
22420 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73  _v2().  Otherwis
22430 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65  e, various.** fe
22440 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75  atures that requ
22450 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  ire the use of t
22460 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d  emporary files m
22470 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53  ay fail..**.** S
22480 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
22490 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
224a0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
224b0 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63  _open(.  const c
224c0 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
224d0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
224e0 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
224f0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
22500 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
22510 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
22520 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
22530 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
22540 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
22550 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
22560 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
22570 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
22580 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
22590 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
225a0 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
225b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
225c0 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
225d0 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
225e0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
225f0 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
22600 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
22610 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
22620 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
22630 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
22640 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
22650 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
22660 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
22670 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
22680 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
22690 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
226a0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
226b0 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49  n Values For URI
226c0 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
226d0 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c  * These are util
226e0 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73  ity routines, us
226f0 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c  eful to VFS impl
22700 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61  ementations, tha
22710 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65  t check.** to se
22720 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20  e if a database 
22730 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74  file was a URI t
22740 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20  hat contained a 
22750 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a  specific query .
22760 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e  ** parameter, an
22770 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20  d if so obtains 
22780 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61  the value of tha
22790 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  t query paramete
227a0 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73  r..**.** If F is
227b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
227c0 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70  lename pointer p
227d0 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
227e0 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66  Open() method of
227f0 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65   .** a VFS imple
22800 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74  mentation when t
22810 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
22820 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61  er to xOpen() ha
22830 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72  s one or .** mor
22840 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  e of the [SQLITE
22850 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53  _OPEN_URI] or [S
22860 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
22870 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64  DB] bits set and
22880 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d  .** P is the nam
22890 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70  e of the query p
228a0 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a  arameter, then.*
228b0 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  * sqlite3_uri_pa
228c0 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
228d0 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  urns the value o
228e0 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d  f the P.** param
228f0 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74  eter if it exist
22900 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s or a NULL poin
22910 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  ter if P does no
22920 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a  t appear as a .*
22930 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
22940 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73  r on F.  If P is
22950 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74   a query paramet
22960 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e  er of F.** has n
22970 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65  o explicit value
22980 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
22990 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
229a0 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70  ) returns.** a p
229b0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70  ointer to an emp
229c0 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ty string..**.**
229d0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
229e0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
229f0 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20  routine assumes 
22a00 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c  that P is a bool
22a10 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ean.** parameter
22a20 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75   and returns tru
22a30 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28  e (1) or false (
22a40 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  0) according to 
22a50 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  the value.** of 
22a60 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  P.  The sqlite3_
22a70 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
22a80 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  B) routine retur
22a90 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74  ns true (1) if t
22aa0 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71  he.** value of q
22ab0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
22ac0 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22   is one of "yes"
22ad0 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e  , "true", or "on
22ae0 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65  " in any.** case
22af0 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
22b00 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
22b10 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20  on-zero number. 
22b20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   The .** sqlite3
22b30 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
22b40 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ,B) routines ret
22b50 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69  urns false (0) i
22b60 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a  f the value of.*
22b70 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
22b80 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e  r P is one of "n
22b90 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20  o", "false", or 
22ba0 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73  "off" in any cas
22bb0 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76  e or.** if the v
22bc0 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
22bd0 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e   a numeric zero.
22be0 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20    If P is not a 
22bf0 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
22c00 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68  er on F or if th
22c10 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
22c20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61  does not match a
22c30 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f  ny of the.** abo
22c40 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ve, then sqlite3
22c50 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
22c60 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d  ,B) returns (B!=
22c70 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  0)..**.** The sq
22c80 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
22c90 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63  F,P,D) routine c
22ca0 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75  onverts the valu
22cb0 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a  e of P into a.**
22cc0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
22cd0 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72  nteger and retur
22ce0 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c  ns that integer,
22cf0 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20   or D if P does 
22d00 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49  not.** exist.  I
22d10 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
22d20 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74   is something ot
22d30 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65  her than an inte
22d40 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72  ger, then.** zer
22d50 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  o is returned..*
22d60 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20  * .** If F is a 
22d70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
22d80 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
22d90 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
22da0 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a  turns NULL and.*
22db0 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
22dc0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
22dd0 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73  urns B.  If F is
22de0 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   not a NULL poin
22df0 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f  ter and.** is no
22e00 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
22e10 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74  e pathname point
22e20 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70  er that SQLite p
22e30 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
22e40 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68  Open.** VFS meth
22e50 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  od, then the beh
22e60 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f  avior of this ro
22e70 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e  utine is undefin
22e80 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a  ed and probably.
22e90 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ** undesirable..
22ea0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
22eb0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
22ec0 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20  eter(const char 
22ed0 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73  *zFilename, cons
22ee0 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b  t char *zParam);
22ef0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69  .int sqlite3_uri
22f00 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63  _boolean(const c
22f10 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73  har *zFile, cons
22f20 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20  t char *zParam, 
22f30 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73  int bDefault);.s
22f40 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
22f50 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63  ite3_uri_int64(c
22f60 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73  onst char*, cons
22f70 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33  t char*, sqlite3
22f80 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  _int64);.../*.**
22f90 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
22fa0 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
22fb0 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ges.**.** ^The s
22fc0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
22fd0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
22fe0 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b  ns the numeric [
22ff0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a  result code] or.
23000 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
23010 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
23020 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61  e most recent fa
23030 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41  iled sqlite3_* A
23040 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63  PI call.** assoc
23050 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61  iated with a [da
23060 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
23070 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41  n]. If a prior A
23080 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a  PI call failed.*
23090 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72  * but the most r
230a0 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73  ecent API call s
230b0 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65  ucceeded, the re
230c0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a  turn value from.
230d0 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  ** sqlite3_errco
230e0 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  de() is undefine
230f0 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
23100 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
23110 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
23120 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63   is the same exc
23130 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61  ept that it alwa
23140 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a  ys returns the .
23150 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
23160 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77  ult code] even w
23170 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73  hen extended res
23180 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a  ult codes are.**
23190 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
231a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
231b0 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74  rmsg() and sqlit
231c0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65  e3_errmsg16() re
231d0 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
231e0 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68  guage.** text th
231f0 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
23200 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65   error, as eithe
23210 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
23220 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
23230 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
23240 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
23250 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
23260 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
23270 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ly..** The appli
23280 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  cation does not 
23290 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62  need to worry ab
232a0 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20  out freeing the 
232b0 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76  result..** Howev
232c0 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74  er, the error st
232d0 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76  ring might be ov
232e0 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61  erwritten or dea
232f0 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73  llocated by.** s
23300 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
23310 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  to other SQLite 
23320 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
23330 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ons.)^.**.** ^Th
23340 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72  e sqlite3_errstr
23350 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
23360 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68  urns the English
23370 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a  -language text.*
23380 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  * that describes
23390 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64   the [result cod
233a0 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a  e], as UTF-8..**
233b0 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
233c0 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
233d0 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
233e0 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
233f0 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74  .** and must not
23400 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65   be freed by the
23410 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a   application)^..
23420 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73  **.** When the s
23430 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
23440 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e  ding mode] is in
23450 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62   use, it might b
23460 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68  e the.** case th
23470 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f  at a second erro
23480 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65  r occurs on a se
23490 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e  parate thread in
234a0 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
234b0 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73  time of the firs
234c0 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20  t error and the 
234d0 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e  call to these in
234e0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65  terfaces..** Whe
234f0 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20  n that happens, 
23500 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  the second error
23510 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65   will be reporte
23520 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a  d since these.**
23530 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61   interfaces alwa
23540 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f  ys report the mo
23550 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74  st recent result
23560 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74  .  To avoid.** t
23570 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64  his, each thread
23580 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c   can obtain excl
23590 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65  usive use of the
235a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
235b0 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69  ction] D.** by i
235c0 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
235d0 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73  _mutex_enter]([s
235e0 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
235f0 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69  (D)) before begi
23600 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20  nning.** to use 
23610 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b  D and invoking [
23620 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
23630 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ave]([sqlite3_db
23640 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65  _mutex](D)) afte
23650 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74  r.** all calls t
23660 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73  o the interfaces
23670 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65   listed here are
23680 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a   completed..**.*
23690 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63  * If an interfac
236a0 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c  e fails with SQL
236b0 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74  ITE_MISUSE, that
236c0 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72   means the inter
236d0 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f  face.** was invo
236e0 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ked incorrectly 
236f0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
23700 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73  on.  In that cas
23710 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20  e, the.** error 
23720 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
23730 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20   may or may not 
23740 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73  be set..*/.int s
23750 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73  qlite3_errcode(s
23760 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74  qlite3 *db);.int
23770 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
23780 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  d_errcode(sqlite
23790 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68  3 *db);.const ch
237a0 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  ar *sqlite3_errm
237b0 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f  sg(sqlite3*);.co
237c0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
237d0 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74  3_errmsg16(sqlit
237e0 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  e3*);.const char
237f0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72   *sqlite3_errstr
23800 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
23810 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74  PI3REF: SQL Stat
23820 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20  ement Object.** 
23830 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61  KEYWORDS: {prepa
23840 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b  red statement} {
23850 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23860 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  nts}.**.** An in
23870 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
23880 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
23890 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
238a0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73  atement..** This
238b0 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f   object is vario
238c0 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20  usly known as a 
238d0 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  "prepared statem
238e0 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f  ent" or a.** "co
238f0 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65  mpiled SQL state
23900 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20  ment" or simply 
23910 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22  as a "statement"
23920 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65  ..**.** The life
23930 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20   of a statement 
23940 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65  object goes some
23950 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a  thing like this:
23960 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
23970 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f  li> Create the o
23980 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
23990 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
239a0 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a  )] or a related.
239b0 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e  **      function
239c0 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76  ..** <li> Bind v
239d0 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70  alues to [host p
239e0 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67  arameters] using
239f0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
23a00 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e  d_*().**      in
23a10 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69  terfaces..** <li
23a20 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79  > Run the SQL by
23a30 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
23a40 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72  3_step()] one or
23a50 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
23a60 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73  <li> Reset the s
23a70 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
23a80 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
23a90 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a   then go back.**
23aa0 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e        to step 2.
23ab0 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f    Do this zero o
23ac0 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
23ad0 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68   <li> Destroy th
23ae0 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
23af0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
23b00 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  ()]..** </ol>.**
23b10 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63  .** Refer to doc
23b20 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e  umentation on in
23b30 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73  dividual methods
23b40 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74   above for addit
23b50 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
23b60 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
23b70 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
23b80 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  stmt sqlite3_stm
23b90 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
23ba0 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d  EF: Run-time Lim
23bb0 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  its.**.** ^(This
23bc0 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
23bd0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61  s the size of va
23be0 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73  rious constructs
23bf0 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a   to be limited.*
23c00 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f  * on a connectio
23c10 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  n by connection 
23c20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73  basis.  The firs
23c30 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
23c40 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
23c50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73  connection] whos
23c60 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65  e limit is to be
23c70 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e   set or queried.
23c80 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
23c90 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65  parameter is one
23ca0 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63   of the [limit c
23cb0 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20  ategories] that 
23cc0 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73  define a.** clas
23cd0 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20  s of constructs 
23ce0 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74  to be size limit
23cf0 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70  ed.  The third p
23d00 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
23d10 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72  ** new limit for
23d20 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e   that construct.
23d30 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  )^.**.** ^If the
23d40 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20   new limit is a 
23d50 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c  negative number,
23d60 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e   the limit is un
23d70 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f  changed..** ^(Fo
23d80 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74  r each limit cat
23d90 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d  egory SQLITE_LIM
23da0 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74  IT_<i>NAME</i> t
23db0 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c  here is a .** [l
23dc0 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70  imits | hard upp
23dd0 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74  er bound].** set
23de0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
23df0 20 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65   by a C preproce
23e00 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65  ssor macro calle
23e10 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53  d.** [limits | S
23e20 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d  QLITE_MAX_<i>NAM
23e30 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20  E</i>]..** (The 
23e40 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65  "_LIMIT_" in the
23e50 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64   name is changed
23e60 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a   to "_MAX_".))^.
23e70 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20  ** ^Attempts to 
23e80 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74  increase a limit
23e90 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20   above its hard 
23ea0 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a  upper bound are.
23eb0 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e  ** silently trun
23ec0 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72  cated to the har
23ed0 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a  d upper bound..*
23ee0 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73  *.** ^Regardless
23ef0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
23f00 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73  ot the limit was
23f10 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a   changed, the .*
23f20 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  * [sqlite3_limit
23f30 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
23f40 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20  turns the prior 
23f50 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d  value of the lim
23f60 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74  it..** ^Hence, t
23f70 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65  o find the curre
23f80 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69  nt value of a li
23f90 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e  mit without chan
23fa0 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70  ging it,.** simp
23fb0 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69  ly invoke this i
23fc0 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68  nterface with th
23fd0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
23fe0 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a  r set to -1..**.
23ff0 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ** Run-time limi
24000 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ts are intended 
24010 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69  for use in appli
24020 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e  cations that man
24030 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69  age.** both thei
24040 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64  r own internal d
24050 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f  atabase and also
24060 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20   databases that 
24070 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a  are controlled.*
24080 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65  * by untrusted e
24090 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e  xternal sources.
240a0 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70    An example app
240b0 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62  lication might b
240c0 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73  e a.** web brows
240d0 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20  er that has its 
240e0 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f  own databases fo
240f0 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72  r storing histor
24100 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74  y and.** separat
24110 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74  e databases cont
24120 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63  rolled by JavaSc
24130 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  ript application
24140 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20  s downloaded.** 
24150 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74  off the Internet
24160 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20  .  The internal 
24170 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65  databases can be
24180 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61   given the.** la
24190 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d  rge, default lim
241a0 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20  its.  Databases 
241b0 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72  managed by exter
241c0 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a  nal sources can.
241d0 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68  ** be given much
241e0 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20   smaller limits 
241f0 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76  designed to prev
24200 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20  ent a denial of 
24210 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63  service.** attac
24220 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d  k.  Developers m
24230 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74  ight also want t
24240 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74  o use the [sqlit
24250 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
24260 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  r()].** interfac
24270 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e  e to further con
24280 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53  trol untrusted S
24290 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  QL.  The size of
242a0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
242b0 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75   created by an u
242c0 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20  ntrusted script 
242d0 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64  can be contained
242e0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d   using the.** [m
242f0 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
24300 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e  PRAGMA]..**.** N
24310 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ew run-time limi
24320 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79  t categories may
24330 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
24340 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f  ure releases..*/
24350 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d  .int sqlite3_lim
24360 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  it(sqlite3*, int
24370 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29   id, int newVal)
24380 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24390 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69  F: Run-Time Limi
243a0 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20  t Categories.** 
243b0 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74  KEYWORDS: {limit
243c0 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d   category} {*lim
243d0 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a  it categories}.*
243e0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
243f0 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69  ants define vari
24400 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ous performance 
24410 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63  limits.** that c
24420 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74  an be lowered at
24430 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20   run-time using 
24440 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
24450 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73  ]..** The synops
24460 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e  is of the meanin
24470 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75  gs of the variou
24480 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77  s limits is show
24490 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69  n below..** Addi
244a0 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
244b0 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  on is available 
244c0 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d  at [limits | Lim
244d0 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a  its in SQLite]..
244e0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
244f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
24500 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
24510 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c  TE_LIMIT_LENGTH<
24520 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
24530 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
24540 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  any string or BL
24550 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c  OB or table row,
24560 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e   in bytes.<dd>)^
24570 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
24580 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
24590 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
245a0 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
245b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
245c0 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
245d0 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  of an SQL statem
245e0 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f  ent, in bytes.</
245f0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
24600 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
24610 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  N]] ^(<dt>SQLITE
24620 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64  _LIMIT_COLUMN</d
24630 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
24640 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
24650 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62  columns in a tab
24660 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72  le definition or
24670 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c   in the.** resul
24680 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
24690 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d  CT] or the maxim
246a0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
246b0 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
246c0 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44  .** or in an ORD
246d0 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42  ER BY or GROUP B
246e0 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e  Y clause.</dd>)^
246f0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
24700 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
24710 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
24720 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
24730 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
24740 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
24750 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
24760 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
24770 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
24780 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
24790 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d  COMPOUND_SELECT]
247a0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
247b0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
247c0 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LECT</dt>.** <dd
247d0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
247e0 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
247f0 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43  a compound SELEC
24800 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  T statement.</dd
24810 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
24820 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
24830 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
24840 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64  LIMIT_VDBE_OP</d
24850 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
24860 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
24870 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20  instructions in 
24880 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  a virtual machin
24890 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65  e program.** use
248a0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
248b0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
248c0 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20    This limit is 
248d0 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a  not currently.**
248e0 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67   enforced, thoug
248f0 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  h that might be 
24900 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75  added in some fu
24910 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
24920 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29  ** SQLite.</dd>)
24930 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
24940 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
24950 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ARG]] ^(<dt>SQLI
24960 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
24970 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  N_ARG</dt>.** <d
24980 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
24990 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
249a0 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  s on a function.
249b0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
249c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
249d0 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51  ACHED]] ^(<dt>SQ
249e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
249f0 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HED</dt>.** <dd>
24a00 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
24a10 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20  er of [ATTACH | 
24a20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
24a30 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  es].)^</dd>.**.*
24a40 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
24a50 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
24a60 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  NGTH]].** ^(<dt>
24a70 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
24a80 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
24a90 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
24aa0 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
24ab0 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61  of the pattern a
24ac0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
24ad0 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f  LIKE] or.** [GLO
24ae0 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64  B] operators.</d
24af0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
24b00 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
24b10 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e  LE_NUMBER]].** ^
24b20 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
24b30 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
24b40 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  R</dt>.** <dd>Th
24b50 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20  e maximum index 
24b60 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70  number of any [p
24b70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20  arameter] in an 
24b80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e  SQL statement.)^
24b90 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
24ba0 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
24bb0 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
24bc0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
24bd0 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
24be0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
24bf0 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f  epth of recursio
24c00 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c  n for triggers.<
24c10 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
24c20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24c30 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
24c40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24c50 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
24c60 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
24c70 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
24c80 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
24c90 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
24ca0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24cb0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
24cc0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
24cd0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
24ce0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
24cf0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
24d00 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
24d10 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
24d20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
24d30 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
24d40 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
24d50 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
24d60 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
24d70 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
24d80 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
24d90 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
24da0 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
24db0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
24dc0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
24dd0 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
24de0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
24df0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
24e00 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65             9.#de
24e10 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
24e20 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20  T_TRIGGER_DEPTH 
24e30 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f             10../
24e40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
24e50 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
24e60 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59  Statement.** KEY
24e70 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74  WORDS: {SQL stat
24e80 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a  ement compiler}.
24e90 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
24ea0 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
24eb0 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
24ec0 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
24ed0 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
24ee0 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
24ef0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
24f00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
24f10 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
24f20 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
24f30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
24f40 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
24f50 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
24f60 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
24f70 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
24f80 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
24f90 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
24fa0 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61  en16()].  The da
24fb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24fc0 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20  n must not have 
24fd0 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  been closed..**.
24fe0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
24ff0 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20  gument, "zSql", 
25000 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
25010 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
25020 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
25030 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
25040 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
25050 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
25060 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
25070 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66  e_v2().** interf
25080 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20  aces use UTF-8, 
25090 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
250a0 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69  are16() and sqli
250b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
250c0 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36  ().** use UTF-16
250d0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
250e0 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
250f0 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  s less than zero
25100 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
25110 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  ead up to the.**
25120 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
25130 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74  inator. ^If nByt
25140 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
25150 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68  e, then it is th
25160 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d  e maximum.** num
25170 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65  ber of  bytes re
25180 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e  ad from zSql.  ^
25190 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f  When nByte is no
251a0 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a  n-negative, the.
251b0 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65  ** zSql string e
251c0 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68  nds at either th
251d0 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f  e first '\000' o
251e0 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61  r '\u0000' chara
251f0 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e  cter or.** the n
25200 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68  Byte-th byte, wh
25210 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
25220 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c  rst. If the call
25230 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74  er knows.** that
25240 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74   the supplied st
25250 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d  ring is nul-term
25260 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65  inated, then the
25270 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a  re is a small.**
25280 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76   performance adv
25290 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69  antage to be gai
252a0 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61  ned by passing a
252b0 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
252c0 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75  r that.** is equ
252d0 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72  al to the number
252e0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
252f0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69   input string <i
25300 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a  >including</i>.*
25310 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e  * the nul-termin
25320 61 74 6f 72 20 62 79 74 65 73 20 61 73 20 74 68  ator bytes as th
25330 69 73 20 73 61 76 65 73 20 53 51 4c 69 74 65 20  is saves SQLite 
25340 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a  from having to.*
25350 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66  * make a copy of
25360 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
25370 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54  g..**.** ^If pzT
25380 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ail is not NULL 
25390 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20  then *pzTail is 
253a0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
253b0 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a   the first byte.
253c0 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  ** past the end 
253d0 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c  of the first SQL
253e0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
253f0 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ql.  These routi
25400 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70  nes only.** comp
25410 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74  ile the first st
25420 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c  atement in zSql,
25430 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c   so *pzTail is l
25440 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a  eft pointing to.
25450 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20  ** what remains 
25460 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a  uncompiled..**.*
25470 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65  * ^*ppStmt is le
25480 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61  ft pointing to a
25490 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61   compiled [prepa
254a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
254b0 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78  hat can be.** ex
254c0 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ecuted using [sq
254d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20  lite3_step()].  
254e0 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20  ^If there is an 
254f0 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69  error, *ppStmt i
25500 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  s set.** to NULL
25510 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74  .  ^If the input
25520 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e   text contains n
25530 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e  o SQL (if the in
25540 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a  put is an empty.
25550 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ** string or a c
25560 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
25570 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
25580 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ULL..** The call
25590 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73  ing procedure is
255a0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
255b0 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
255c0 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74  mpiled.** SQL st
255d0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
255e0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
255f0 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20  )] after it has 
25600 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
25610 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20  ..** ppStmt may 
25620 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  not be NULL..**.
25630 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20  ** ^On success, 
25640 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  the sqlite3_prep
25650 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20  are() family of 
25660 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
25670 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20  [SQLITE_OK];.** 
25680 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  otherwise an [er
25690 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
256a0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
256b0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
256c0 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65  _v2() and sqlite
256d0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
256e0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a   interfaces are.
256f0 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  ** recommended f
25700 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72  or all new progr
25710 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64  ams. The two old
25720 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  er interfaces ar
25730 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f  e retained.** fo
25740 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
25750 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74  atibility, but t
25760 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63  heir use is disc
25770 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20  ouraged..** ^In 
25780 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
25790 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65  ces, the prepare
257a0 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  d statement.** t
257b0 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20  hat is returned 
257c0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
257d0 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74  mt] object) cont
257e0 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  ains a copy of t
257f0 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
25800 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61  QL text. This ca
25810 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65  uses the [sqlite
25820 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66  3_step()] interf
25830 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65  ace to.** behave
25840 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20   differently in 
25850 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a  three ways:.**.*
25860 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a  * <ol>.** <li>.*
25870 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
25880 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
25890 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65  s, instead of re
258a0 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
258b0 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a  SCHEMA] as it.**
258c0 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20   always used to 
258d0 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  do, [sqlite3_ste
258e0 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61  p()] will automa
258f0 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
25900 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61  e the SQL.** sta
25910 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74  tement and try t
25920 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20  o run it again. 
25930 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49  As many as [SQLI
25940 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45  TE_MAX_SCHEMA_RE
25950 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20  TRY].** retries 
25960 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72  will occur befor
25970 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
25980 20 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 65   gives up and re
25990 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a  turns an error..
259a0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
259b0 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20  li>.** ^When an 
259c0 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73  error occurs, [s
259d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
259e0 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  ill return one o
259f0 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a  f the detailed.*
25a00 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  * [error codes] 
25a10 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
25a20 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65  or codes].  ^The
25a30 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
25a40 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71   was that.** [sq
25a50 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
25a60 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
25a70 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54  a generic [SQLIT
25a80 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
25a90 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20  code.** and the 
25aa0 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c  application woul
25ab0 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61  d have to make a
25ac0 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20   second call to 
25ad0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
25ae0 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f  ].** in order to
25af0 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c   find the underl
25b00 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68  ying cause of th
25b10 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20  e problem. With 
25b20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65  the "v2" prepare
25b30 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20  .** interfaces, 
25b40 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72  the underlying r
25b50 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72  eason for the er
25b60 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
25b70 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20  immediately..** 
25b80 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
25b90 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63  .** ^If the spec
25ba0 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64  ific value bound
25bb0 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c   to [parameter |
25bc0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d   host parameter]
25bd0 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52   in the .** WHER
25be0 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69  E clause might i
25bf0 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f  nfluence the cho
25c00 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
25c10 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e  n for a statemen
25c20 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73  t,.** then the s
25c30 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65  tatement will be
25c40 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
25c50 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66  ecompiled, as if
25c60 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20   there had been 
25c70 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61  .** a schema cha
25c80 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73  nge, on the firs
25c90 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  t  [sqlite3_step
25ca0 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69  ()] call followi
25cb0 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a  ng any change.**
25cc0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
25cd0 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e  _bind_text | bin
25ce0 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b  dings] of that [
25cf0 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20  parameter]. .** 
25d00 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61  ^The specific va
25d10 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61  lue of WHERE-cla
25d20 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  use [parameter] 
25d30 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
25d40 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f  the .** choice o
25d50 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20  f query plan if 
25d60 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
25d70 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73   the left-hand s
25d80 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a  ide of a [LIKE].
25d90 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65  ** or [GLOB] ope
25da0 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20  rator or if the 
25db0 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d  parameter is com
25dc0 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65  pared to an inde
25dd0 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e  xed column.** an
25de0 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e  d the [SQLITE_EN
25df0 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70  ABLE_STAT3] comp
25e00 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
25e10 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74  is enabled..** t
25e20 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  he .** </li>.** 
25e30 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  </ol>.*/.int sql
25e40 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20  ite3_prepare(.  
25e50 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
25e60 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
25e70 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
25e80 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
25e90 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
25ea0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
25eb0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
25ec0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
25ed0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
25ee0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
25ef0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
25f00 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
25f10 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
25f20 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
25f30 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
25f40 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
25f50 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
25f60 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
25f70 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
25f80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
25f90 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
25fa0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
25fb0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
25fc0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
25fd0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
25fe0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
25ff0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
26000 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
26010 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
26020 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
26030 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
26040 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
26050 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
26060 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
26070 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
26080 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
26090 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
260a0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
260b0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
260c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
260d0 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74  epare16(.  sqlit
260e0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
260f0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
26100 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
26110 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
26120 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
26130 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
26140 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
26150 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
26160 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
26170 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
26180 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
26190 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
261a0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
261b0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
261c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
261d0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
261e0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
261f0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
26200 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
26210 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
26220 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
26230 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
26240 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
26250 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
26260 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
26270 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
26280 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
26290 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
262a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
262b0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
262c0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
262d0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
262e0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
262f0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
26300 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
26310 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
26320 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
26330 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
26340 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
26350 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26360 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61  : Retrieving Sta
26370 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a  tement SQL.**.**
26380 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
26390 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
263a0 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64  retrieve a saved
263b0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69   copy of the ori
263c0 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78  ginal.** SQL tex
263d0 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  t used to create
263e0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
263f0 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20  tement] if that 
26400 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a  statement was.**
26410 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20   compiled using 
26420 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
26430 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
26440 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
26450 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f  e16_v2()]..*/.co
26460 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
26470 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  3_sql(sqlite3_st
26480 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
26490 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
264a0 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
264b0 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65   Statement Write
264c0 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a  s The Database.*
264d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
264e0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
264f0 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  X) interface ret
26500 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
26510 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f  ero) if.** and o
26520 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70  nly if the [prep
26530 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
26540 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63  X makes no direc
26550 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20  t changes to.** 
26560 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
26570 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
26580 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
26590 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  t [application-d
265a0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
265b0 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72  ions] or.** [vir
265c0 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67  tual tables] mig
265d0 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ht change the da
265e0 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c  tabase indirectl
265f0 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65  y as a side effe
26600 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65  ct.  .** ^(For e
26610 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70  xample, if an ap
26620 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
26630 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76  s a function "ev
26640 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63  al()" that .** c
26650 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78  alls [sqlite3_ex
26660 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  ec()], then the 
26670 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74  following SQL st
26680 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a  atement would.**
26690 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
266a0 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67  base file throug
266b0 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a  h side-effects:.
266c0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
266d0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45  e><pre>.**    SE
266e0 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54  LECT eval('DELET
266f0 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d  E FROM t1') FROM
26700 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f   t2;.** </pre></
26710 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
26720 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68  * But because th
26730 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
26740 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68  ment does not ch
26750 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
26760 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74  e file.** direct
26770 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  ly, sqlite3_stmt
26780 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c  _readonly() woul
26790 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74  d still return t
267a0 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72  rue.)^.**.** ^Tr
267b0 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
267c0 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63  l statements suc
267d0 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43  h as [BEGIN], [C
267e0 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43  OMMIT], [ROLLBAC
267f0 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e  K],.** [SAVEPOIN
26800 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45  T], and [RELEASE
26810 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f  ] cause sqlite3_
26820 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
26830 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a  to return true,.
26840 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61  ** since the sta
26850 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76  tements themselv
26860 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c  es do not actual
26870 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  ly modify the da
26880 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61  tabase but.** ra
26890 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f  ther they contro
268a0 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20  l the timing of 
268b0 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65  when other state
268c0 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65  ments modify the
268d0 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20   .** database.  
268e0 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e  ^The [ATTACH] an
268f0 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65  d [DETACH] state
26900 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65  ments also cause
26910 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  .** sqlite3_stmt
26920 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
26930 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65  eturn true since
26940 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74  , while those st
26950 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e  atements.** chan
26960 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  ge the configura
26970 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61  tion of a databa
26980 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74  se connection, t
26990 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20  hey do not make 
269a0 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74  .** changes to t
269b0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
269c0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  e database files
269d0 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74   on disk..*/.int
269e0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
269f0 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73  adonly(sqlite3_s
26a00 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
26a10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
26a20 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65  termine If A Pre
26a30 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
26a40 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a  Has Been Reset.*
26a50 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a60 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69  3_stmt_busy(S) i
26a70 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
26a80 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
26a90 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   if the.** [prep
26aa0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
26ab0 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70  S has been stepp
26ac0 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65  ed at least once
26ad0 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
26ae0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74  te3_step(S)] but
26af0 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20   has not run to 
26b00 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f  completion and/o
26b10 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65  r has not .** be
26b20 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b  en reset using [
26b30 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
26b40 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
26b50 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a  _stmt_busy(S).**
26b60 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
26b70 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73  ns false if S is
26b80 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
26b90 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20    If S is not a 
26ba0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
26bb0 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f   and is not a po
26bc0 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64  inter to a valid
26bd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26be0 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c  ment].** object,
26bf0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
26c00 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  or is undefined 
26c10 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
26c20 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  esirable..**.** 
26c30 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
26c40 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f  an be used in co
26c50 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74  mbination [sqlit
26c60 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a  e3_next_stmt()].
26c70 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c  ** to locate all
26c80 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
26c90 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20  ents associated 
26ca0 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20  with a database 
26cb0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
26cc0 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20  hat are in need 
26cd0 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20  of being reset. 
26ce0 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65   This can be use
26cf0 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c  d,.** for exampl
26d00 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63  e, in diagnostic
26d10 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61   routines to sea
26d20 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64  rch for prepared
26d30 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20   .** statements 
26d40 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67  that are holding
26d50 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f   a transaction o
26d60 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  pen..*/.int sqli
26d70 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71  te3_stmt_busy(sq
26d80 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
26d90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
26da0 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64  ynamically Typed
26db0 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a   Value Object.**
26dc0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74   KEYWORDS: {prot
26dd0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
26de0 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65  lue} {unprotecte
26df0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
26e00 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
26e10 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  es the sqlite3_v
26e20 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72  alue object to r
26e30 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c  epresent all val
26e40 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  ues.** that can 
26e50 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64  be stored in a d
26e60 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53  atabase table. S
26e70 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
26e80 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72  ic typing.** for
26e90 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73   the values it s
26ea0 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20  tores.  ^Values 
26eb0 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65  stored in sqlite
26ec0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a  3_value objects.
26ed0 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65  ** can be intege
26ee0 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  rs, floating poi
26ef0 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e  nt values, strin
26f00 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55  gs, BLOBs, or NU
26f10 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c  LL..**.** An sql
26f20 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
26f30 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20  t may be either 
26f40 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22  "protected" or "
26f50 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a  unprotected"..**
26f60 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73   Some interfaces
26f70 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65   require a prote
26f80 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
26f90 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72  ue.  Other inter
26fa0 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63  faces.** will ac
26fb0 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72  cept either a pr
26fc0 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e  otected or an un
26fd0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
26fe0 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72  3_value..** Ever
26ff0 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
27000 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33   accepts sqlite3
27010 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73  _value arguments
27020 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
27030 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20  ether or not it 
27040 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65  requires a prote
27050 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
27060 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65  ue..**.** The te
27070 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20  rms "protected" 
27080 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64  and "unprotected
27090 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68  " refer to wheth
270a0 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d  er or not.** a m
270b0 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41  utex is held.  A
270c0 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78  n internal mutex
270d0 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70   is held for a p
270e0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
270f0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
27100 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73   but no mutex is
27110 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70   held for an unp
27120 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
27130 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
27140 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
27150 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73  compiled to be s
27160 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a  ingle-threaded.*
27170 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  * (with [SQLITE_
27180 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e  THREADSAFE=0] an
27190 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
271a0 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65  threadsafe()] re
271b0 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72  turning 0).** or
271c0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75   if SQLite is ru
271d0 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75  n in one of redu
271e0 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20  ced mutex modes 
271f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
27200 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
27210 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
27220 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a  IG_MULTITHREAD].
27230 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  ** then there is
27240 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20   no distinction 
27250 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
27260 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
27270 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
27280 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74  ue objects and t
27290 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20  hey can be used 
272a0 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e  interchangeably.
272b0 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f    However,.** fo
272c0 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70  r maximum code p
272d0 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73  ortability it is
272e0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
272f0 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  t applications.*
27300 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65  * still make the
27310 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
27320 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
27330 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
27340 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
27350 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65  objects even whe
27360 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72  n not strictly r
27370 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  equired..**.** ^
27380 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
27390 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61  e objects that a
273a0 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72  re passed as par
273b0 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65  ameters into the
273c0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
273d0 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69  on of [applicati
273e0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
273f0 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72  unctions] are pr
27400 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  otected..** ^The
27410 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
27420 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
27430 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
27440 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
27450 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a   unprotected..**
27460 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   Unprotected sql
27470 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
27480 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ts may only be u
27490 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  sed with.** [sql
274a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
274b0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
274c0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e  3_bind_value()].
274d0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
274e0 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71  _value_blob | sq
274f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
27500 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ()] family of.**
27510 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
27520 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71  ire protected sq
27530 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
27540 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  cts..*/.typedef 
27550 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74  struct Mem sqlit
27560 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a  e3_value;../*.**
27570 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46   CAPI3REF: SQL F
27580 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
27590 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
275a0 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63   context in whic
275b0 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  h an SQL functio
275c0 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74  n executes is st
275d0 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71  ored in an.** sq
275e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
275f0 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65  ject.  ^A pointe
27600 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f  r to an sqlite3_
27610 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a  context object.*
27620 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73  * is always firs
27630 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  t parameter to [
27640 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
27650 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
27660 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  s]..** The appli
27670 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
27680 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
27690 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20  ementation will 
276a0 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69  pass this.** poi
276b0 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74  nter through int
276c0 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  o calls to [sqli
276d0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c  te3_result_int |
276e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28   sqlite3_result(
276f0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
27700 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
27710 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75  t()], [sqlite3_u
27720 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  ser_data()],.** 
27730 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
27740 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b  _db_handle()], [
27750 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
27760 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f  ata()],.** and/o
27770 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  r [sqlite3_set_a
27780 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79  uxdata()]..*/.ty
27790 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
277a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c  ite3_context sql
277b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f  ite3_context;../
277c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42  *.** CAPI3REF: B
277d0 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f  inding Values To
277e0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
277f0 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ents.** KEYWORDS
27800 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  : {host paramete
27810 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  r} {host paramet
27820 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ers} {host param
27830 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45  eter name}.** KE
27840 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72  YWORDS: {SQL par
27850 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72  ameter} {SQL par
27860 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65  ameters} {parame
27870 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a  ter binding}.**.
27880 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20  ** ^(In the SQL 
27890 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69  statement text i
278a0 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
278b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
278c0 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c  nd its variants,
278d0 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79  .** literals may
278e0 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20   be replaced by 
278f0 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68  a [parameter] th
27900 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f  at matches one o
27910 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74  f following.** t
27920 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20  emplates:.**.** 
27930 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a  <ul>.** <li>  ?.
27940 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a  ** <li>  ?NNN.**
27950 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c   <li>  :VVV.** <
27960 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69  li>  @VVV.** <li
27970 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e  >  $VVV.** </ul>
27980 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65  .**.** In the te
27990 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e  mplates above, N
279a0 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  NN represents an
279b0 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c   integer literal
279c0 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70  ,.** and VVV rep
279d0 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61  resents an alpha
279e0 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69  numeric identifi
279f0 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75  er.)^  ^The valu
27a00 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70  es of these.** p
27a10 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20  arameters (also 
27a20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72  called "host par
27a30 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72  ameter names" or
27a40 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   "SQL parameters
27a50 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74  ").** can be set
27a60 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
27a70 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
27a80 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72  ines defined her
27a90 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
27aa0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
27ab0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
27ac0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73  _*() routines is
27ad0 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69   always.** a poi
27ae0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
27af0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
27b00 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a  t returned from.
27b10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
27b20 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
27b30 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a   variants..**.**
27b40 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
27b50 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
27b60 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61  ex of the SQL pa
27b70 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65  rameter to be se
27b80 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d  t..** ^The leftm
27b90 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ost SQL paramete
27ba0 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
27bb0 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20  f 1.  ^When the 
27bc0 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51  same named.** SQ
27bd0 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75  L parameter is u
27be0 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  sed more than on
27bf0 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ce, second and s
27c00 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63  ubsequent.** occ
27c10 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68  urrences have th
27c20 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20  e same index as 
27c30 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
27c40 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e  ence..** ^The in
27c50 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61  dex for named pa
27c60 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20  rameters can be 
27c70 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20  looked up using 
27c80 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
27c90 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
27ca0 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64  ndex()] API if d
27cb0 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e  esired.  ^The in
27cc0 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e  dex.** for "?NNN
27cd0 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  " parameters is 
27ce0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e  the value of NNN
27cf0 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61  ..** ^The NNN va
27d00 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77  lue must be betw
27d10 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73  een 1 and the [s
27d20 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
27d30 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51  ** parameter [SQ
27d40 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
27d50 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66  BLE_NUMBER] (def
27d60 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29  ault value: 999)
27d70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
27d80 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
27d90 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
27da0 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
27db0 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68  r..** ^If the th
27dc0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
27dd0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
27de0 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
27df0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
27e00 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
27e10 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c  _blob() is a NUL
27e20 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
27e30 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
27e40 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65  ter.** is ignore
27e50 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65  d and the end re
27e60 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65  sult is the same
27e70 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   as sqlite3_bind
27e80 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  _null()..**.** ^
27e90 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e  (In those routin
27ea0 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66  es that have a f
27eb0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  ourth argument, 
27ec0 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65  its value is the
27ed0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  .** number of by
27ee0 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d  tes in the param
27ef0 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65  eter.  To be cle
27f00 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73  ar: the value is
27f10 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
27f20 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69  f <u>bytes</u> i
27f30 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74  n the value, not
27f40 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
27f50 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20  haracters.)^.** 
27f60 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
27f70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
27f80 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20  te3_bind_text() 
27f90 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
27fa0 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e  text16().** is n
27fb0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
27fc0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
27fd0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65  string is.** the
27fe0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
27ff0 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
28000 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
28010 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72  ..** If the four
28020 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
28030 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
28040 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c  b() is negative,
28050 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68   then.** the beh
28060 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
28070 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d  ed..** If a non-
28080 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20  negative fourth 
28090 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f  parameter is pro
280a0 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33  vided to sqlite3
280b0 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20  _bind_text().** 
280c0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
280d0 74 65 78 74 31 36 28 29 20 74 68 65 6e 20 74 68  text16() then th
280e0 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  at parameter mus
280f0 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66  t be the byte of
28100 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68  fset.** where th
28110 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
28120 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73   would occur ass
28130 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67  uming the string
28140 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72   were NUL.** ter
28150 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
28160 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
28170 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66  occur at byte of
28180 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20  fsets less than 
28190 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66  .** the value of
281a0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
281b0 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72  meter then the r
281c0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
281d0 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f  value will.** co
281e0 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e  ntain embedded N
281f0 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ULs.  The result
28200 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
28210 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67  involving string
28220 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64  s.** with embedd
28230 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
28240 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
28250 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
28260 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
28270 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
28280 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64  bind_text(), and
28290 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
282a0 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64  _text16() is a d
282b0 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
282c0 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
282d0 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
282e0 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
282f0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
28300 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74  h it.  ^The dest
28310 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
28320 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  .** to dispose o
28330 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74  f the BLOB or st
28340 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ring even if the
28350 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
28360 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a  _bind_blob(),.**
28370 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
28380 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  xt(), or sqlite3
28390 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66  _bind_text16() f
283a0 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74  ails.  .** ^If t
283b0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
283c0 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63  t is.** the spec
283d0 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  ial value [SQLIT
283e0 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20  E_STATIC], then 
283f0 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
28400 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72  hat the.** infor
28410 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61  mation is in sta
28420 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73  tic, unmanaged s
28430 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
28440 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65  t need to be fre
28450 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ed..** ^If the f
28460 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61  ifth argument ha
28470 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c  s the value [SQL
28480 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
28490 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  then.** SQLite m
284a0 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69  akes its own pri
284b0 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
284c0 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c   data immediatel
284d0 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  y, before.** the
284e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
284f0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
28500 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
28510 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
28520 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
28530 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
28540 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
28550 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
28560 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c  roes.  ^A zerobl
28570 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20  ob uses a fixed 
28580 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
28590 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74  .** (just an int
285a0 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73  eger to hold its
285b0 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20   size) while it 
285c0 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73  is being process
285d0 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73  ed..** Zeroblobs
285e0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f   are intended to
285f0 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68   serve as placeh
28600 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73  olders for BLOBs
28610 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e   whose.** conten
28620 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74  t is later writt
28630 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  en using.** [sql
28640 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
28650 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
28660 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e  B I/O] routines.
28670 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20  .** ^A negative 
28680 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
28690 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
286a0 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
286b0 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  BLOB..**.** ^If 
286c0 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74  any of the sqlit
286d0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
286e0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
286f0 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
28700 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b  ter.** for the [
28710 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28720 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72  nt] or with a pr
28730 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28740 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73   for which.** [s
28750 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
28760 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d  as been called m
28770 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61  ore recently tha
28780 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
28790 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ()],.** then the
287a0 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72   call will retur
287b0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
287c0 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74  ].  If any sqlit
287d0 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f  e3_bind_().** ro
287e0 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20  utine is passed 
287f0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
28800 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20  ement] that has 
28810 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20  been finalized, 
28820 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73  the.** result is
28830 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
28840 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e  robably harmful.
28850 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73  .**.** ^Bindings
28860 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64   are not cleared
28870 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
28880 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e  _reset()] routin
28890 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70  e..** ^Unbound p
288a0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
288b0 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
288c0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
288d0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75  lite3_bind_* rou
288e0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
288f0 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
28900 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72  ess or an.** [er
28910 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79  ror code] if any
28920 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
28930 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
28940 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
28950 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
28960 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
28970 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
28980 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
28990 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
289a0 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
289b0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
289c0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
289d0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
289e0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
289f0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
28a00 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
28a10 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
28a20 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
28a30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
28a40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
28a50 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
28a60 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
28a70 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
28a80 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
28a90 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
28aa0 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69   int, double);.i
28ab0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
28ac0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
28ad0 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e  *, int, int);.in
28ae0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
28af0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
28b00 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
28b10 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c  _int64);.int sql
28b20 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73  ite3_bind_null(s
28b30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
28b40 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
28b50 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
28b60 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
28b70 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e  nst char*, int n
28b80 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
28b90 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
28ba0 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
28bb0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
28bc0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
28bd0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
28be0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
28bf0 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  nd_value(sqlite3
28c00 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
28c10 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  st sqlite3_value
28c20 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
28c30 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  bind_zeroblob(sq
28c40 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
28c50 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
28c60 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
28c70 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74  r Of SQL Paramet
28c80 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ers.**.** ^This 
28c90 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
28ca0 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
28cb0 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
28cc0 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
28cd0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
28ce0 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
28cf0 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
28d00 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
28d10 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
28d20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
28d30 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
28d40 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
28d50 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
28d60 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
28d70 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
28d80 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
28d90 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
28da0 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
28db0 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
28dc0 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75  ne actually retu
28dd0 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66  rns the index of
28de0 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69   the largest (ri
28df0 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61  ghtmost).** para
28e00 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66  meter. For all f
28e10 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e  orms except ?NNN
28e20 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72  , this will corr
28e30 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a  espond to the.**
28e40 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75   number of uniqu
28e50 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49  e parameters.  I
28e60 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  f parameters of 
28e70 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72  the ?NNN form ar
28e80 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65  e used,.** there
28e90 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20   may be gaps in 
28ea0 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a  the list.)^.**.*
28eb0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
28ec0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
28ed0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
28ee0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
28ef0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
28f00 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
28f10 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
28f20 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
28f30 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
28f40 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
28f50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
28f60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28f70 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
28f80 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a   Parameter.**.**
28f90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
28fa0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
28fb0 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  e(P,N) interface
28fc0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
28fd0 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68  name of the N-th
28fe0 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
28ff0 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
29000 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
29010 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74  ** ^(SQL paramet
29020 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
29030 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
29040 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
29050 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
29060 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
29070 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
29080 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
29090 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
290a0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
290b0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
290c0 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
290d0 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
290e0 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
290f0 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
29100 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e  the name.)^.** ^
29110 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  Parameters of th
29120 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f  e form "?" witho
29130 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69  ut a following i
29140 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e  nteger have no n
29150 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72  ame.** and are r
29160 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e  eferred to as "n
29170 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f  ameless" or "ano
29180 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
29190 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  s"..**.** ^The f
291a0 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
291b0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
291c0 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
291d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75  .** ^If the valu
291e0 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e N is out of ra
291f0 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d  nge or if the N-
29200 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
29210 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65  ** nameless, the
29220 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
29230 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
29240 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  ed string is.** 
29250 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20  always in UTF-8 
29260 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
29270 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
29280 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67  eter was.** orig
29290 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
292a0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
292b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
292c0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
292d0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
292e0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
292f0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
29300 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
29310 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
29320 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
29330 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
29340 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
29350 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
29360 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  x()]..*/.const c
29370 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e  har *sqlite3_bin
29380 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
29390 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
293a0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
293b0 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
293c0 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
293d0 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a   A Given Name.**
293e0 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
293f0 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
29400 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
29410 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a  its name.  ^The.
29420 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72  ** index value r
29430 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61  eturned is suita
29440 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74  ble for use as t
29450 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72  he second.** par
29460 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
29470 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
29480 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e  ite3_bind()].  ^
29490 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74  A zero.** is ret
294a0 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63  urned if no matc
294b0 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69  hing parameter i
294c0 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70  s found.  ^The p
294d0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
294e0 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
294f0 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
29500 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
29510 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
29520 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
29530 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
29540 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
29550 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
29560 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
29570 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
29580 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
29590 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
295a0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
295b0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
295c0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
295d0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
295e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
295f0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71  rameter_index(sq
29600 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e  lite3_stmt*, con
29610 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
29620 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29630 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64  : Reset All Bind
29640 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72  ings On A Prepar
29650 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed Statement.**.
29660 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20  ** ^Contrary to 
29670 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
29680 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
29690 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
296a0 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b  t reset.** the [
296b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
296c0 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
296d0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
296e0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65  tement]..** ^Use
296f0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
29700 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20   reset all host 
29710 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55  parameters to NU
29720 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  LL..*/.int sqlit
29730 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
29740 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  s(sqlite3_stmt*)
29750 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29760 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c  F: Number Of Col
29770 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74  umns In A Result
29780 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75   Set.**.** ^Retu
29790 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
297a0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
297b0 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
297c0 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70  ned by the.** [p
297d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
297e0 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  t]. ^This routin
297f0 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70  e returns 0 if p
29800 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a  Stmt is an SQL.*
29810 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  * statement that
29820 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e   does not return
29830 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70   data (for examp
29840 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e  le an [UPDATE]).
29850 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
29860 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
29870 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73  ount()].*/.int s
29880 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
29890 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
298a0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
298b0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d   CAPI3REF: Colum
298c0 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73  n Names In A Res
298d0 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  ult Set.**.** ^T
298e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
298f0 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73  turn the name as
29900 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74  signed to a part
29910 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  icular column.**
29920 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
29930 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
29940 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68   statement.  ^Th
29950 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
29960 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72  _name().** inter
29970 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
29980 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
29990 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
299a0 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20  8 string.** and 
299b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
299c0 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20  ame16() returns 
299d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
299e0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
299f0 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  * UTF-16 string.
29a00 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72    ^The first par
29a10 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70  ameter is the [p
29a20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29a30 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65  t].** that imple
29a40 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43  ments the [SELEC
29a50 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54  T] statement. ^T
29a60 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
29a70 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  ter is the.** co
29a80 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54  lumn number.  ^T
29a90 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
29aa0 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a  mn is number 0..
29ab0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  **.** ^The retur
29ac0 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ned string point
29ad0 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  er is valid unti
29ae0 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72  l either the [pr
29af0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29b00 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65  ].** is destroye
29b10 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69  d by [sqlite3_fi
29b20 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
29b30 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
29b40 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
29b50 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
29b60 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
29b70 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
29b80 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
29b90 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
29ba0 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
29bb0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
29bc0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
29bd0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
29be0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74  mn_name16() on t
29bf0 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
29c00 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  **.** ^If sqlite
29c10 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
29c20 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
29c30 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
29c40 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
29c50 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
29c60 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
29c70 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
29c80 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
29c90 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
29ca0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
29cb0 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
29cc0 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
29cd0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
29ce0 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
29cf0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
29d00 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
29d10 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
29d20 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
29d30 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
29d40 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
29d50 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
29d60 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
29d70 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
29d80 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
29d90 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e  the next..*/.con
29da0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
29db0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
29dc0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
29dd0 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  N);.const void *
29de0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
29df0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
29e00 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
29e10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
29e20 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
29e30 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
29e40 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
29e50 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
29e60 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
29e70 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20  e the database, 
29e80 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61  table, and.** ta
29e90 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
29ea0 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66  is the origin of
29eb0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
29ec0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a  sult column in.*
29ed0 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  * [SELECT] state
29ee0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61  ment..** ^The na
29ef0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
29f00 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
29f10 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
29f20 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
29f30 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
29f40 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
29f50 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
29f60 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
29f70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
29f80 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
29f90 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
29fa0 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
29fb0 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
29fc0 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
29fd0 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
29fe0 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  me..** ^The retu
29ff0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
2a000 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b  alid until the [
2a010 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a020 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
2a030 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
2a040 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2a050 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
2a060 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
2a070 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
2a080 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
2a090 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2a0a0 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
2a0b0 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
2a0c0 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
2a0d0 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
2a0e0 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
2a0f0 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66   again in a diff
2a100 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a  erent encoding..
2a110 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73  **.** ^The names
2a120 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
2a130 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
2a140 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
2a150 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
2a160 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
2a170 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  n..**.** ^The fi
2a180 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
2a190 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
2a1a0 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
2a1b0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
2a1c0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2a1d0 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
2a1e0 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68  on about the Nth
2a1f0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72   result column r
2a200 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68  eturned by.** th
2a210 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65  e statement, whe
2a220 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
2a230 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
2a240 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65  ment..** ^The le
2a250 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  ft-most column i
2a260 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74  s column 0 for t
2a270 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
2a280 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68  *.** ^If the Nth
2a290 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
2a2a0 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
2a2b0 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  t is an expressi
2a2c0 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72  on or.** subquer
2a2d0 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63  y and is not a c
2a2e0 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65  olumn value, the
2a2f0 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66  n all of these f
2a300 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a  unctions return.
2a310 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65  ** NULL.  ^These
2a320 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61   routine might a
2a330 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  lso return NULL 
2a340 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
2a350 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20  cation error.** 
2a360 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77  occurs.  ^Otherw
2a370 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
2a380 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2a390 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
2a3a0 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72  se, table,.** or
2a3b0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
2a3c0 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ry result column
2a3d0 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
2a3e0 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77  rom..**.** ^As w
2a3f0 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
2a400 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
2a410 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64   whose names end
2a420 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
2a430 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
2a440 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20  ded strings and 
2a450 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69  the other functi
2a460 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38  ons return UTF-8
2a470 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41  ..**.** ^These A
2a480 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61  PIs are only ava
2a490 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
2a4a0 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
2a4b0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
2a4c0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
2a4d0 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
2a4e0 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
2a4f0 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  mbol..**.** If t
2a500 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
2a510 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
2a520 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
2a530 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
2a540 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
2a550 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
2a560 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
2a570 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
2a580 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
2a590 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2a5a0 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
2a5b0 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
2a5c0 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71  e or more.** [sq
2a5d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
2a5e0 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c  abase_name | col
2a5f0 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
2a600 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20  erfaces].** for 
2a610 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
2a620 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
2a630 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
2a640 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ** at the same t
2a650 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
2a660 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2a670 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  ed..*/.const cha
2a680 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2a690 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28  n_database_name(
2a6a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2a6b0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
2a6c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2a6d0 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
2a6e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2a6f0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
2a700 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
2a710 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
2a720 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2a730 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2a740 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
2a750 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2a760 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
2a770 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2a780 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
2a790 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2a7a0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
2a7b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
2a7c0 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  rigin_name16(sql
2a7d0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2a7e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a7f0 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74  : Declared Datat
2a800 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52  ype Of A Query R
2a810 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  esult.**.** ^(Th
2a820 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2a830 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
2a840 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2a850 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
2a860 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20  t is a [SELECT] 
2a870 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
2a880 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
2a890 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  the.** returned 
2a8a0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
2a8b0 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61  at [SELECT] is a
2a8c0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
2a8d0 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
2a8e0 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
2a8f0 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
2a900 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
2a910 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
2a920 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e  s returned.)^  ^
2a930 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
2a940 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
2a950 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70  set is an.** exp
2a960 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
2a970 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  ery, then a NULL
2a980 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
2a990 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  rned..** ^The re
2a9a0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
2a9b0 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e   always UTF-8 en
2a9c0 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  coded..**.** ^(F
2a9d0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65  or example, give
2a9e0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  n the database s
2a9f0 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45  chema:.**.** CRE
2aa00 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20  ATE TABLE t1(c1 
2aa10 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20  VARIANT);.**.** 
2aa20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  and the followin
2aa30 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  g statement to b
2aa40 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  e compiled:.**.*
2aa50 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
2aa60 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
2aa70 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ** this routine 
2aa80 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
2aa90 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
2aaa0 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
2aab0 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
2aac0 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
2aad0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
2aae0 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
2aaf0 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e  t column (i==0).
2ab00 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
2ab10 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
2ab20 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
2ab30 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65  ^So just because
2ab40 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20   a column.** is 
2ab50 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74  declared to cont
2ab60 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ain a particular
2ab70 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d   type does not m
2ab80 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ean that the.** 
2ab90 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74  data stored in t
2aba0 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66  hat column is of
2abb0 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
2abc0 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a  pe.  SQLite is.*
2abd0 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64  * strongly typed
2abe0 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67  , but the typing
2abf0 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20   is dynamic not 
2ac00 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a  static.  ^Type.*
2ac10 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
2ac20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
2ac30 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
2ac40 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
2ac50 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
2ac60 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f  those values..*/
2ac70 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2ac80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
2ac90 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
2aca0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
2acb0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2acc0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73  umn_decltype16(s
2acd0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2ace0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2acf0 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20  EF: Evaluate An 
2ad00 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
2ad10 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65  .** After a [pre
2ad20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2ad30 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72   has been prepar
2ad40 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a  ed using either.
2ad50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2ad60 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
2ad70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2ad80 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
2ad90 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
2ada0 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
2adb0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
2adc0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2add0 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63  16()], this func
2ade0 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20  tion.** must be 
2adf0 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
2ae00 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
2ae10 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  uate the stateme
2ae20 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
2ae30 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
2ae40 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c  avior of the sql
2ae50 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
2ae60 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
2ae70 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
2ae80 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
2ae90 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
2aea0 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72  newer "v2" inter
2aeb0 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  face.** [sqlite3
2aec0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
2aed0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2aee0 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
2aef0 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
2af00 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71  ** interface [sq
2af10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
2af20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2af30 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
2af40 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
2af50 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  ew "v2" interfac
2af60 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
2af70 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
2af80 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
2af90 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2afa0 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
2afb0 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
2afc0 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c  .**.** ^In the l
2afd0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
2afe0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2aff0 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72  e will be either
2b000 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a   [SQLITE_BUSY],.
2b010 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
2b020 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
2b030 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
2b040 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
2b050 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  E]..** ^With the
2b060 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
2b070 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65   any of the othe
2b080 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  r [result codes]
2b090 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
2b0a0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d   result codes] m
2b0b0 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
2b0c0 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20   as well..**.** 
2b0d0 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d  ^[SQLITE_BUSY] m
2b0e0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61  eans that the da
2b0f0 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61  tabase engine wa
2b100 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75  s unable to acqu
2b110 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ire the.** datab
2b120 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65  ase locks it nee
2b130 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62  ds to do its job
2b140 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65  .  ^If the state
2b150 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49  ment is a [COMMI
2b160 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20  T].** or occurs 
2b170 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78  outside of an ex
2b180 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
2b190 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e  on, then you can
2b1a0 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74   retry the.** st
2b1b0 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65  atement.  If the
2b1c0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
2b1d0 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64  t a [COMMIT] and
2b1e0 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
2b1f0 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72  n.** explicit tr
2b200 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79  ansaction then y
2b210 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61  ou should rollba
2b220 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
2b230 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e  on before.** con
2b240 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  tinuing..**.** ^
2b250 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
2b260 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
2b270 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
2b280 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
2b290 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
2b2a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
2b2b0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
2b2c0 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
2b2d0 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
2b2e0 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
2b2f0 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
2b300 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
2b310 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
2b320 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
2b330 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
2b340 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49   state..**.** ^I
2b350 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
2b360 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
2b370 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
2b380 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ata, then [SQLIT
2b390 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74  E_ROW].** is ret
2b3a0 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
2b3b0 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
2b3c0 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70  a is ready for p
2b3d0 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
2b3e0 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  .** caller. The 
2b3f0 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
2b400 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65  cessed using the
2b410 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
2b420 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
2b430 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
2b440 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
2b450 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
2b460 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
2b470 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45  **.** ^[SQLITE_E
2b480 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74  RROR] means that
2b490 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
2b4a0 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e  r (such as a con
2b4b0 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61  straint.** viola
2b4c0 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72  tion) has occurr
2b4d0 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ed.  sqlite3_ste
2b4e0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
2b4f0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
2b500 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72  n.** the VM. Mor
2b510 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61  e information ma
2b520 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61  y be found by ca
2b530 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
2b540 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69  rrmsg()]..** ^Wi
2b550 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  th the legacy in
2b560 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20  terface, a more 
2b570 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
2b580 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ode (for example
2b590 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  ,.** [SQLITE_INT
2b5a0 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45  ERRUPT], [SQLITE
2b5b0 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54  _SCHEMA], [SQLIT
2b5c0 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20  E_CORRUPT], and 
2b5d0 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e  so forth).** can
2b5e0 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20   be obtained by 
2b5f0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2b600 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65  _reset()] on the
2b610 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2b620 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74  atement].  ^In t
2b630 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2b640 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  e,.** the more s
2b650 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
2b660 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64  de is returned d
2b670 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74  irectly by sqlit
2b680 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a  e3_step()..**.**
2b690 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2b6a0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2b6b0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73  this routine was
2b6c0 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70   called inapprop
2b6d0 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68  riately..** Perh
2b6e0 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65  aps it was calle
2b6f0 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  d on a [prepared
2b700 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2b710 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20   has.** already 
2b720 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  been [sqlite3_fi
2b730 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
2b740 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68  ed] or on one th
2b750 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f  at had.** previo
2b760 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53  usly returned [S
2b770 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20  QLITE_ERROR] or 
2b780 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
2b790 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62  Or it could.** b
2b7a0 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
2b7b0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
2b7c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2b7d0 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77  being used by tw
2b7e0 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72  o or.** more thr
2b7f0 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
2b800 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e   moment in time.
2b810 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76  .**.** For all v
2b820 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
2b830 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c  e up to and incl
2b840 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20  uding 3.6.23.1, 
2b850 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
2b860 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
2b870 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65  as required afte
2b880 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  r sqlite3_step()
2b890 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69   returned anythi
2b8a0 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e  ng.** other than
2b8b0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65   [SQLITE_ROW] be
2b8c0 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75  fore any subsequ
2b8d0 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ent invocation o
2b8e0 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  f.** sqlite3_ste
2b8f0 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f  p().  Failure to
2b900 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
2b910 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73  red statement us
2b920 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
2b930 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20  _reset()] would 
2b940 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51  result in an [SQ
2b950 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74  LITE_MISUSE] ret
2b960 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  urn from.** sqli
2b970 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74  te3_step().  But
2b980 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33   after version 3
2b990 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33  .6.23.1, sqlite3
2b9a0 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a  _step() began.**
2b9b0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2b9c0 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d  3_reset()] autom
2b9d0 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73  atically in this
2b9e0 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61   circumstance ra
2b9f0 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74  ther.** than ret
2ba00 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d  urning [SQLITE_M
2ba10 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73  ISUSE].  This is
2ba20 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20   not considered 
2ba30 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a  a compatibility.
2ba40 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65  ** break because
2ba50 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e   any application
2ba60 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69   that ever recei
2ba70 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49  ves an SQLITE_MI
2ba80 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73  SUSE error.** is
2ba90 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e   broken by defin
2baa0 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c  ition.  The [SQL
2bab0 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53  ITE_OMIT_AUTORES
2bac0 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ET] compile-time
2bad0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62   option.** can b
2bae0 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72  e used to restor
2baf0 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
2bb00 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  avior..**.** <b>
2bb10 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
2bb20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68  Alert:</b> In th
2bb30 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
2bb40 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
2bb50 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c  step().** API al
2bb60 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
2bb70 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
2bb80 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  e, [SQLITE_ERROR
2bb90 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
2bba0 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20  .** error other 
2bbb0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
2bbc0 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  Y] and [SQLITE_M
2bbd0 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
2bbe0 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
2bbf0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
2bc00 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2bc10 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
2bc20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a  find one of the.
2bc30 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  ** specific [err
2bc40 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
2bc50 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
2bc60 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
2bc70 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
2bc80 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
2bc90 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
2bca0 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
2bcb0 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
2bcc0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
2bcd0 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
2bce0 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
2bcf0 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
2bd00 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
2bd10 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2bd20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2bd30 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61  e16_v2()] instea
2bd40 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
2bd50 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
2bd60 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
2bd70 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2bd80 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20   interfaces,.** 
2bd90 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70  then the more sp
2bda0 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
2bdb0 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
2bdc0 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
2bdd0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
2bde0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
2bdf0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
2be00 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
2be10 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
2be20 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tep(sqlite3_stmt
2be30 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2be40 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63  REF: Number of c
2be50 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75  olumns in a resu
2be60 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  lt set.**.** ^Th
2be70 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2be80 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63  ount(P) interfac
2be90 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2bea0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2beb0 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  in the.** curren
2bec0 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
2bed0 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70  ult set of [prep
2bee0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2bef0 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72  P..** ^If prepar
2bf00 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64  ed statement P d
2bf10 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73  oes not have res
2bf20 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65  ults ready to re
2bf30 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c  turn.** (via cal
2bf40 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ls to the [sqlit
2bf50 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20  e3_column_int | 
2bf60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a  sqlite3_column_*
2bf70 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ()] of.** interf
2bf80 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74  aces) then sqlit
2bf90 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2bfa0 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e   returns 0..** ^
2bfb0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2bfc0 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
2bfd0 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30  e also returns 0
2bfe0 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20   if P is a NULL 
2bff0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65  pointer..** ^The
2c000 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2c010 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72  unt(P) routine r
2c020 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20  eturns 0 if the 
2c030 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
2c040 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2c050 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b  p](P) returned [
2c060 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e  SQLITE_DONE].  ^
2c070 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2c080 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c  _count(P).** wil
2c090 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72  l return non-zer
2c0a0 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61  o if previous ca
2c0b0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2c0c0 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
2c0d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  .** [SQLITE_ROW]
2c0e0 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20  , except in the 
2c0f0 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41  case of the [PRA
2c100 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f  GMA incremental_
2c110 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65  vacuum].** where
2c120 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
2c130 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61  ns zero since ea
2c140 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20  ch step of that 
2c150 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72  multi-step.** pr
2c160 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63  agma returns 0 c
2c170 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a  olumns of data..
2c180 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2c190 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2c1a0 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20  count()].*/.int 
2c1b0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2c1c0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
2c1d0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2c1e0 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d  CAPI3REF: Fundam
2c1f0 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a  ental Datatypes.
2c200 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
2c210 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e  ITE_TEXT.**.** ^
2c220 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20  (Every value in 
2c230 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f  SQLite has one o
2c240 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74  f five fundament
2c250 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a  al datatypes:.**
2c260 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
2c270 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
2c280 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36  nteger.** <li> 6
2c290 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74  4-bit IEEE float
2c2a0 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
2c2b0 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a  .** <li> string.
2c2c0 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20  ** <li> BLOB.** 
2c2d0 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75  <li> NULL.** </u
2c2e0 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  l>)^.**.** These
2c2f0 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63   constants are c
2c300 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66  odes for each of
2c310 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a   those types..**
2c320 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
2c330 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f  e SQLITE_TEXT co
2c340 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20  nstant was also 
2c350 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76  used in SQLite v
2c360 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20  ersion 2.** for 
2c370 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66  a completely dif
2c380 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20  ferent meaning. 
2c390 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c   Software that l
2c3a0 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74  inks against bot
2c3b0 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  h.** SQLite vers
2c3c0 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65  ion 2 and SQLite
2c3d0 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c   version 3 shoul
2c3e0 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45  d use SQLITE3_TE
2c3f0 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54  XT, not.** SQLIT
2c400 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69  E_TEXT..*/.#defi
2c410 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  ne SQLITE_INTEGE
2c420 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  R  1.#define SQL
2c430 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23  ITE_FLOAT    2.#
2c440 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c  define SQLITE_BL
2c450 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65  OB     4.#define
2c460 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20   SQLITE_NULL    
2c470 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45   5.#ifdef SQLITE
2c480 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51  _TEXT.# undef SQ
2c490 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a  LITE_TEXT.#else.
2c4a0 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
2c4b0 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69  TEXT     3.#endi
2c4c0 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  f.#define SQLITE
2c4d0 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a  3_TEXT     3../*
2c4e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2c4f0 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d  sult Values From
2c500 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57   A Query.** KEYW
2c510 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63  ORDS: {column ac
2c520 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a  cess functions}.
2c530 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2c540 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72  ines form the "r
2c550 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72  esult set" inter
2c560 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  face..**.** ^The
2c570 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
2c580 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
2c590 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f  bout a single co
2c5a0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72  lumn of the curr
2c5b0 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  ent.** result ro
2c5c0 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e  w of a query.  ^
2c5d0 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68  In every case th
2c5e0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2c5f0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   is a pointer.**
2c600 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
2c610 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2c620 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75  t is being evalu
2c630 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  ated (the [sqlit
2c640 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61  e3_stmt*].** tha
2c650 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66  t was returned f
2c660 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  rom [sqlite3_pre
2c670 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
2c680 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
2c690 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65  s).** and the se
2c6a0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
2c6b0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
2c6c0 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
2c6d0 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ch information.*
2c6e0 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
2c6f0 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d  rned. ^The leftm
2c700 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
2c710 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73  e result set has
2c720 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a   the index 0..**
2c730 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
2c740 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
2c750 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74  esult can be det
2c760 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a  ermined using.**
2c770 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2c780 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _count()]..**.**
2c790 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
2c7a0 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
2c7b0 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74  urrently point t
2c7c0 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f  o a valid row, o
2c7d0 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r if the.** colu
2c7e0 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  mn index is out 
2c7f0 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65  of range, the re
2c800 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
2c810 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  d..** These rout
2c820 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
2c830 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
2c840 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2c850 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2c860 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
2c870 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
2c880 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
2c890 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2c8a0 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
2c8b0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76  _finalize()] hav
2c8c0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75  e been called su
2c8d0 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49  bsequently..** I
2c8e0 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  f any of these r
2c8f0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2c900 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
2c910 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
2c920 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2c930 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b  ze()] or after [
2c940 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2c950 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  has returned.** 
2c960 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
2c970 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
2c980 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ], the results a
2c990 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
2c9a0 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   If [sqlite3_ste
2c9b0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
2c9c0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
2c9d0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2c9e0 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  ].** are called 
2c9f0 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74  from a different
2ca00 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e   thread while an
2ca10 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
2ca20 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69  nes.** are pendi
2ca30 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ng, then the res
2ca40 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2ca50 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2ca60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2ca70 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
2ca80 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  urns the.** [SQL
2ca90 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
2caa0 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
2cab0 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
2cac0 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
2cad0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
2cae0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76   ^The returned v
2caf0 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
2cb00 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
2cb10 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
2cb20 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
2cb30 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
2cb40 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
2cb50 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a  L].  The value.*
2cb60 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
2cb70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2cb80 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
2cb90 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70  ingful if no typ
2cba0 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73  e.** conversions
2cbb0 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61   have occurred a
2cbc0 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f  s described belo
2cbd0 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65  w.  After a type
2cbe0 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20   conversion,.** 
2cbf0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
2cc00 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2cc10 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75  lumn_type() is u
2cc20 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72  ndefined.  Futur
2cc30 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
2cc40 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
2cc50 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
2cc60 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
2cc70 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
2cc80 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
2cc90 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  version..**.** ^
2cca0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2ccb0 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
2ccc0 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
2ccd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2cce0 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69  bytes().** routi
2ccf0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
2cd00 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2cd10 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
2cd20 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2cd30 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
2cd40 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65  F-16 string, the
2cd50 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2cd60 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74  _bytes() convert
2cd70 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
2cd80 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65  to UTF-8 and the
2cd90 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
2cda0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
2cdb0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2cdc0 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
2cdd0 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
2cde0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2cdf0 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
2ce00 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
2ce10 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
2ce20 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
2ce30 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2ce40 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2ce50 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2ce60 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2ce70 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
2ce80 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
2ce90 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72  column_bytes() r
2cea0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
2ceb0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2cec0 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
2ced0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65  TF-16 string the
2cee0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
2cef0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a  lumn_bytes16().*
2cf00 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
2cf10 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2cf20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
2cf30 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
2cf40 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2cf50 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
2cf60 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
2cf70 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2cf80 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
2cf90 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31   string to UTF-1
2cfa0 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  6 and then retur
2cfb0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2cfc0 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
2cfd0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
2cfe0 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
2cff0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2d000 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a  _bytes16() uses.
2d010 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
2d020 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
2d030 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
2d040 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
2d050 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
2d060 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2d070 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
2d080 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2d090 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
2d0a0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2d0b0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74  mn_bytes16() ret
2d0c0 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
2d0d0 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
2d0e0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
2d0f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2d100 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74  ] and .** [sqlit
2d110 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2d120 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c  6()] do not incl
2d130 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
2d140 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20  minators at the 
2d150 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
2d160 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72  ring.  ^For clar
2d170 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20  ity: the values 
2d180 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
2d190 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d1a0 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c  ytes()] and [sql
2d1b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d1c0 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e  s16()] are the n
2d1d0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
2d1e0 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
2d1f0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
2d200 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
2d210 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65  *.** ^Strings re
2d220 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2d230 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2d240 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2d250 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
2d260 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  even empty strin
2d270 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
2d280 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
2d290 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20   ^The return.** 
2d2a0 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
2d2b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2d2c0 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67   for a zero-leng
2d2d0 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c  th BLOB is a NUL
2d2e0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
2d2f0 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74   ^The object ret
2d300 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
2d310 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
2d320 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
2d330 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2d340 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
2d350 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  An unprotected s
2d360 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2d370 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  ect.** may only 
2d380 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71  be used with [sq
2d390 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
2d3a0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2d3b0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
2d3c0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70  ..** If the [unp
2d3d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d3e0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72  _value] object r
2d3f0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
2d400 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2d410 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69  lue()] is used i
2d420 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c  n any other way,
2d430 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73   including calls
2d440 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  .** to routines 
2d450 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  like [sqlite3_va
2d460 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c  lue_int()], [sql
2d470 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2d480 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
2d490 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
2d4a0 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ], then the beha
2d4b0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
2d4c0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  d..**.** These r
2d4d0 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20  outines attempt 
2d4e0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
2d4f0 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f  alue where appro
2d500 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a  priate.  ^For.**
2d510 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
2d520 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
2d530 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
2d540 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
2d550 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
2d560 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
2d570 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
2d580 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
2d590 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63  perform the.** c
2d5a0 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61  onversion automa
2d5b0 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20  tically.  ^(The 
2d5c0 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
2d5d0 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
2d5e0 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
2d5f0 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
2d600 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
2d610 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
2d620 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
2d630 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
2d640 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
2d650 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
2d660 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
2d670 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
2d680 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2d690 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
2d6a0 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
2d6b0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
2d6c0 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
2d6d0 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
2d6e0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2d6f0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2d700 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
2d710 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
2d720 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2d730 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2d740 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
2d750 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
2d760 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
2d770 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2d780 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
2d790 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
2d7a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2d7b0 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
2d7c0 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
2d7d0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
2d7e0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
2d7f0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
2d800 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2d810 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45  > Same as INTEGE
2d820 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
2d830 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
2d840 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2d850 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c   Convert from fl
2d860 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a  oat to integer.*
2d870 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2d880 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
2d890 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
2d8a0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
2d8b0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
2d8c0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
2d8d0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
2d8e0 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58  me as FLOAT->TEX
2d8f0 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  T.** <tr><td>  T
2d900 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
2d910 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61  GER   <td> Use a
2d920 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
2d930 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
2d940 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55   FLOAT    <td> U
2d950 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
2d960 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
2d970 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2d980 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
2d990 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
2d9a0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2d9b0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
2d9c0 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
2d9d0 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
2d9e0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
2d9f0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
2da00 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
2da10 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a  hen use atof().*
2da20 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
2da30 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
2da40 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
2da50 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
2da60 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
2da70 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
2da80 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ote>)^.**.** The
2da90 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b   table above mak
2daa0 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20  es reference to 
2dab0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
2dac0 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f  ry functions ato
2dad0 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28  i().** and atof(
2dae0 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20  ).  SQLite does 
2daf0 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74  not really use t
2db00 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
2db10 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f   It has its.** o
2db20 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e  wn equivalent in
2db30 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e  ternal routines.
2db40 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64    The atoi() and
2db50 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72   atof() names ar
2db60 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65  e.** used in the
2db70 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69   table for brevi
2db80 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74  ty and because t
2db90 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72  hey are familiar
2dba0 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72   to most.** C pr
2dbb0 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a  ogrammers..**.**
2dbc0 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
2dbd0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
2dbe0 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
2dbf0 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
2dc00 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
2dc10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2dc20 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
2dc30 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
2dc40 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
2dc50 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
2dc60 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
2dc70 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
2dc80 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
2dc90 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
2dca0 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
2dcb0 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
2dcc0 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
2dcd0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
2dce0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
2dcf0 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
2dd00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2dd10 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
2dd20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2dd30 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
2dd40 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
2dd50 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
2dd60 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
2dd70 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
2dd80 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
2dd90 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
2dda0 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
2ddb0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2ddc0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
2ddd0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
2dde0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2ddf0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
2de00 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
2de10 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
2de20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
2de30 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
2de40 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
2de50 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
2de60 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2de70 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
2de80 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
2de90 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
2dea0 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
2deb0 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
2dec0 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
2ded0 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
2dee0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  ul>.**.** ^Conve
2def0 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
2df00 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
2df10 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
2df20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
2df30 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
2df40 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
2df50 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
2df60 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
2df70 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
2df80 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
2df90 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66  rior pointer ref
2dfa0 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76  erences will hav
2dfb0 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
2dfc0 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
2dfd0 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
2dfe0 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
2dff0 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
2e000 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
2e010 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
2e020 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
2e030 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
2e040 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
2e050 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
2e060 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
2e070 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20   and easiest to 
2e080 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20  remember policy 
2e090 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
2e0a0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
2e0b0 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
2e0c0 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
2e0d0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
2e0e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2e0f0 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
2e100 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2e110 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
2e120 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
2e130 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
2e140 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
2e150 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
2e160 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
2e170 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2e180 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
2e190 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e1a0 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
2e1b0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
2e1c0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
2e1d0 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
2e1e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2e1f0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
2e200 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
2e210 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e220 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
2e230 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
2e240 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
2e250 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
2e260 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
2e270 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2e280 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
2e290 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2e2a0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
2e2b0 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
2e2c0 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
2e2d0 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
2e2e0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
2e2f0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
2e300 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
2e310 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
2e320 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2e330 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
2e340 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
2e350 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2e360 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
2e370 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2e380 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
2e390 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20  * ^The pointers 
2e3a0 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
2e3b0 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
2e3c0 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
2e3d0 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
2e3e0 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
2e3f0 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
2e400 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
2e410 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
2e420 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2e430 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e  )] is called.  ^
2e440 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
2e450 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
2e460 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f  rings.** and BLO
2e470 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  Bs is freed auto
2e480 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c  matically.  Do <
2e490 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74  b>not</b> pass t
2e4a0 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
2e4b0 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rned.** [sqlite3
2e4c0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c  _column_blob()],
2e4d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2e4e0 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69  _text()], etc. i
2e4f0 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
2e500 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  free()]..**.** ^
2e510 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  (If a memory all
2e520 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
2e530 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
2e540 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
2e550 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
2e560 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
2e570 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
2e580 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
2e590 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
2e5a0 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
2e5b0 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
2e5c0 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
2e5d0 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
2e5e0 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
2e5f0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
2e600 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
2e610 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
2e620 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
2e630 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  )^.*/.const void
2e640 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2e650 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
2e660 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2e670 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2e680 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
2e690 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2e6a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2e6b0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
2e6c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2e6d0 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73   iCol);.double s
2e6e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
2e6f0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
2e700 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
2e710 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2e720 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
2e730 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2e740 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
2e750 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2e760 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2e770 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
2e780 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
2e790 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2e7a0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
2e7b0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2e7c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2e7d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2e7e0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2e7f0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
2e800 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2e810 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
2e820 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
2e830 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
2e840 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2e850 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2e860 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
2e870 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
2e880 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
2e890 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
2e8a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2e8b0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
2e8c0 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
2e8d0 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
2e8e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e8f0 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  t]..** ^If the m
2e900 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
2e910 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ation of the sta
2e920 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72  tement encounter
2e930 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  ed no errors.** 
2e940 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d  or if the statem
2e950 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65  ent is never bee
2e960 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65  n evaluated, the
2e970 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  n sqlite3_finali
2e980 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  ze() returns.** 
2e990 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20  SQLITE_OK.  ^If 
2e9a0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2e9b0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74  evaluation of st
2e9c0 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64  atement S failed
2e9d0 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
2e9e0 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65  3_finalize(S) re
2e9f0 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70  turns the approp
2ea00 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
2ea10 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
2ea20 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  ed error code]..
2ea30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2ea40 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
2ea50 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
2ea60 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
2ea70 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20  t during.** the 
2ea80 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70  life cycle of [p
2ea90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2eaa0 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20  t] S:.** before 
2eab0 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65  statement S is e
2eac0 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61  ver evaluated, a
2ead0 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d  fter.** one or m
2eae0 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ore calls to [sq
2eaf0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20  lite3_reset()], 
2eb00 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c  or after any cal
2eb10 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  l.** to [sqlite3
2eb20 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c  _step()] regardl
2eb30 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
2eb40 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d  r not the statem
2eb50 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c  ent has.** compl
2eb60 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a  eted execution..
2eb70 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20  **.** ^Invoking 
2eb80 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2eb90 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  () on a NULL poi
2eba0 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65  nter is a harmle
2ebb0 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20  ss no-op..**.** 
2ebc0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
2ebd0 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76  must finalize ev
2ebe0 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74  ery [prepared st
2ebf0 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65  atement] in orde
2ec00 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65  r to avoid.** re
2ec10 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49  source leaks.  I
2ec20 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20  t is a grievous 
2ec30 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70  error for the ap
2ec40 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79  plication to try
2ec50 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65   to use.** a pre
2ec60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2ec70 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
2ec80 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e  n finalized.  An
2ec90 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61  y use of a prepa
2eca0 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
2ecb0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
2ecc0 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e  en finalized can
2ecd0 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
2ece0 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65  ined and.** unde
2ecf0 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
2ed00 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c   such as segfaul
2ed10 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72  ts and heap corr
2ed20 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  uption..*/.int s
2ed30 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2ed40 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2ed50 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2ed60 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
2ed70 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2ed80 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
2ed90 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
2eda0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
2edb0 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
2edc0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2edd0 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  ment].** object 
2ede0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
2edf0 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79  ial state, ready
2ee00 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74   to be re-execut
2ee10 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20  ed..** ^Any SQL 
2ee20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
2ee30 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
2ee40 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
2ee50 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
2ee60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2ee70 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
2ee80 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
2ee90 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
2eea0 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
2eeb0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
2eec0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
2eed0 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ndings..**.** ^T
2eee0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2eef0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
2ef00 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
2ef10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2ef20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65  S.** back to the
2ef30 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74   beginning of it
2ef40 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  s program..**.**
2ef50 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2ef60 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2ef70 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
2ef80 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
2ef90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2efa0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2efb0 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
2efc0 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69  E_DONE],.** or i
2efd0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
2efe0 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
2eff0 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
2f000 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b   on S,.** then [
2f010 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2f020 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
2f030 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  E_OK]..**.** ^If
2f040 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2f050 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2f060 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
2f070 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2f080 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64  statement] S ind
2f090 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c  icated an error,
2f0a0 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65   then.** [sqlite
2f0b0 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
2f0c0 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
2f0d0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
2f0e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
2f0f0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
2f100 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
2f110 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
2f120 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73  ues.** of any [s
2f130 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2f140 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
2f150 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2f160 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74  ement] S..*/.int
2f170 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
2f180 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2f190 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2f1a0 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
2f1b0 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
2f1c0 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ctions.** KEYWOR
2f1d0 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
2f1e0 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
2f1f0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2f200 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2f210 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
2f220 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2f230 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2f240 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2f250 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  }.**.** ^These f
2f260 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63  unctions (collec
2f270 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  tively known as 
2f280 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  "function creati
2f290 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a  on routines").**
2f2a0 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
2f2b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
2f2c0 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20  r aggregates or 
2f2d0 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20  to redefine the 
2f2e0 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65  behavior.** of e
2f2f0 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63  xisting SQL func
2f300 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
2f310 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64  tes.  The only d
2f320 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65  ifferences betwe
2f330 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74  en.** these rout
2f340 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78  ines are the tex
2f350 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63  t encoding expec
2f360 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73  ted for.** the s
2f370 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2f380 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  (the name of the
2f390 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20   function being 
2f3a0 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20  created).** and 
2f3b0 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20  the presence or 
2f3c0 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73  absence of a des
2f3d0 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
2f3e0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c   for.** the appl
2f3f0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
2f400 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
2f410 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2f420 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73   is the [databas
2f430 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
2f440 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a   which the SQL.*
2f450 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f  * function is to
2f460 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20   be added.  ^If 
2f470 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
2f480 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ses more than on
2f490 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
2f4a0 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70  nnection then ap
2f4b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2f4c0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
2f4d0 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a  must be added.**
2f4e0 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
2f4f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70  e connection sep
2f500 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  arately..**.** ^
2f510 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
2f520 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
2f530 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   of the SQL func
2f540 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74  tion to be creat
2f550 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e  ed or.** redefin
2f560 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68  ed.  ^The length
2f570 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20   of the name is 
2f580 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62  limited to 255 b
2f590 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a  ytes in a UTF-8.
2f5a0 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ** representatio
2f5b0 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20  n, exclusive of 
2f5c0 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
2f5d0 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74  tor.  ^Note that
2f5e0 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e   the name.** len
2f5f0 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20  gth limit is in 
2f600 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74  UTF-8 bytes, not
2f610 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20   characters nor 
2f620 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a  UTF-16 bytes.  .
2f630 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20  ** ^Any attempt 
2f640 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63  to create a func
2f650 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67  tion with a long
2f660 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  er name.** will 
2f670 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54  result in [SQLIT
2f680 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20  E_MISUSE] being 
2f690 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2f6a0 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
2f6b0 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69  eter (nArg).** i
2f6c0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2f6d0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74  arguments that t
2f6e0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2f6f0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
2f700 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20  takes. ^If this 
2f710 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c  parameter is -1,
2f720 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75   then the SQL fu
2f730 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
2f740 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20  regate may take 
2f750 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  any number of ar
2f760 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20  guments between 
2f770 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a  0 and the limit.
2f780 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74  ** set by [sqlit
2f790 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54  e3_limit]([SQLIT
2f7a0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
2f7b0 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20  _ARG]).  If the 
2f7c0 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
2f7d0 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  er is less than 
2f7e0 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  -1 or greater th
2f7f0 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20  an 127 then the 
2f800 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75  behavior is.** u
2f810 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2f820 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
2f830 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c  meter, eTextRep,
2f840 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a   specifies what.
2f850 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
2f860 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  | text encoding]
2f870 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69   this SQL functi
2f880 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a  on prefers for.*
2f890 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73  * its parameters
2f8a0 2e 20 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e  .  Every SQL fun
2f8b0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2f8c0 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c  tion must be abl
2f8d0 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74  e to work.** wit
2f8e0 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c  h UTF-8, UTF-16l
2f8f0 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20  e, or UTF-16be. 
2f900 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d   But some implem
2f910 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65  entations may be
2f920 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65  .** more efficie
2f930 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f  nt with one enco
2f940 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65  ding than anothe
2f950 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74  r.  ^An applicat
2f960 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b  ion may.** invok
2f970 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
2f980 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73  _function() or s
2f990 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2f9a0 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69  nction16() multi
2f9b0 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74  ple.** times wit
2f9c0 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  h the same funct
2f9d0 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66  ion but with dif
2f9e0 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66  ferent values of
2f9f0 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57   eTextRep..** ^W
2fa00 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  hen multiple imp
2fa10 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
2fa20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2fa30 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c  n are available,
2fa40 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
2fa50 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61  pick the one tha
2fa60 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c  t involves the l
2fa70 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
2fa80 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ata conversion..
2fa90 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f  ** If there is o
2faa0 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70  nly a single imp
2fab0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63  lementation whic
2fac0 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  h does not care 
2fad0 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63  what text.** enc
2fae0 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  oding is used, t
2faf0 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61  hen the fourth a
2fb00 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
2fb10 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a  e [SQLITE_ANY]..
2fb20 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74  **.** ^(The fift
2fb30 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
2fb40 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e  n arbitrary poin
2fb50 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d  ter.  The implem
2fb60 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  entation of the.
2fb70 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ** function can 
2fb80 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74  gain access to t
2fb90 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e  his pointer usin
2fba0 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  g [sqlite3_user_
2fbb0 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a  data()].)^.**.**
2fbc0 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76   ^The sixth, sev
2fbd0 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20  enth and eighth 
2fbe0 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e  parameters, xFun
2fbf0 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  c, xStep and xFi
2fc00 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e  nal, are.** poin
2fc10 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61  ters to C-langua
2fc20 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ge functions tha
2fc30 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
2fc40 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
2fc50 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41  ** aggregate. ^A
2fc60 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
2fc70 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
2fc80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2fc90 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20  of the xFunc.** 
2fca0 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e  callback only; N
2fcb0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73  ULL pointers mus
2fcc0 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  t be passed as t
2fcd0 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  he xStep and xFi
2fce0 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  nal.** parameter
2fcf0 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65  s. ^An aggregate
2fd00 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
2fd10 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
2fd20 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65  entation of xSte
2fd30 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20  p.** and xFinal 
2fd40 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  and NULL pointer
2fd50 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
2fd60 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64  for xFunc. ^To d
2fd70 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e  elete an existin
2fd80 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  g.** SQL functio
2fd90 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
2fda0 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  pass NULL pointe
2fdb0 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65  rs for all three
2fdc0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c   function.** cal
2fdd0 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  lbacks..**.** ^(
2fde0 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72  If the ninth par
2fdf0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2fe00 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2fe10 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55  n_v2() is not NU
2fe20 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  LL,.** then it i
2fe30 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  s destructor for
2fe40 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2fe50 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a   data pointer. .
2fe60 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  ** The destructo
2fe70 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  r is invoked whe
2fe80 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  n the function i
2fe90 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65  s deleted, eithe
2fea0 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76  r by being.** ov
2feb0 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e  erloaded or when
2fec0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2fed0 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e  nnection closes.
2fee0 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72  )^.** ^The destr
2fef0 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e  uctor is also in
2ff00 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c  voked if the cal
2ff10 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
2ff20 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
2ff30 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e  v2() fails..** ^
2ff40 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63  When the destruc
2ff50 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  tor callback of 
2ff60 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65  the tenth parame
2ff70 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ter is invoked, 
2ff80 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  it.** is passed 
2ff90 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
2ffa0 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70  t which is a cop
2ffb0 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  y of the applica
2ffc0 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f  tion data .** po
2ffd0 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20  inter which was 
2ffe0 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  the fifth parame
2fff0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
30000 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
30010 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  2()..**.** ^It i
30020 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72  s permitted to r
30030 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65  egister multiple
30040 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
30050 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   of the same.** 
30060 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74  functions with t
30070 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
30080 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66   with either dif
30090 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f  fering numbers o
300a0 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f  f.** arguments o
300b0 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66  r differing pref
300c0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
300d0 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77  ings.  ^SQLite w
300e0 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69  ill use.** the i
300f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68  mplementation th
30100 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20  at most closely 
30110 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20  matches the way 
30120 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  in which the.** 
30130 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
30140 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69  used.  ^A functi
30150 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
30160 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67  n with a non-neg
30170 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61  ative.** nArg pa
30180 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74  rameter is a bet
30190 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ter match than a
301a0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
301b0 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a  entation with.**
301c0 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67   a negative nArg
301d0 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  .  ^A function w
301e0 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72  here the preferr
301f0 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
30200 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20  .** matches the 
30210 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e  database encodin
30220 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a  g is a better.**
30230 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
30240 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
30250 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
30260 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20  ferent.  .** ^A 
30270 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
30280 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
30290 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65  erence is betwee
302a0 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54  n UTF16le and UT
302b0 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c  F16be.** is a cl
302c0 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  oser match than 
302d0 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
302e0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
302f0 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62  fference is.** b
30300 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20  etween UTF8 and 
30310 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75  UTF16..**.** ^Bu
30320 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73  ilt-in functions
30330 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64   may be overload
30340 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63  ed by new applic
30350 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
30360 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  nctions..**.** ^
30370 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  An application-d
30380 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
30390 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
303a0 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51  call other.** SQ
303b0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e  Lite interfaces.
303c0 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20    However, such 
303d0 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a  calls must not.*
303e0 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  * close the data
303f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
30400 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20  nor finalize or 
30410 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
30420 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
30430 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e  in which the fun
30440 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
30450 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
30460 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
30470 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
30480 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
30490 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
304a0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
304b0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
304c0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
304d0 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
304e0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
304f0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
30500 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
30510 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
30520 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
30530 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
30540 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
30550 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
30560 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
30570 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  unction16(.  sql
30580 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
30590 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
305a0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
305b0 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
305c0 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
305d0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
305e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
305f0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
30600 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
30610 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
30620 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
30630 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
30640 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
30650 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
30660 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
30670 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
30680 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
30690 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
306a0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
306b0 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
306c0 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
306d0 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
306e0 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
306f0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
30700 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
30710 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
30720 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
30730 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
30740 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
30750 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
30760 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76  3_context*),.  v
30770 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
30780 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
30790 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
307a0 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54  ncodings.**.** T
307b0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
307c0 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
307d0 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
307e0 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
307f0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
30800 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
30810 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
30820 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
30830 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
30840 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
30850 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
30860 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
30870 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
30880 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20  SQLITE_UTF16    
30890 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73        4    /* Us
308a0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
308b0 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  der */.#define S
308c0 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20  QLITE_ANY       
308d0 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c       5    /* sql
308e0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
308f0 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65  tion only */.#de
30900 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
30910 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
30920 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
30930 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
30940 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
30950 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20  REF: Deprecated 
30960 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50  Functions.** DEP
30970 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68  RECATED.**.** Th
30980 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
30990 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20  e [deprecated]. 
309a0 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69   In order to mai
309b0 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72  ntain.** backwar
309c0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
309d0 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65   with older code
309e0 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  , these function
309f0 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74  s continue .** t
30a00 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20  o be supported. 
30a10 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70   However, new ap
30a20 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
30a30 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
30a40 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
30a50 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20  tions.  To help 
30a60 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65  encourage people
30a70 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69   to avoid.** usi
30a80 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ng these functio
30a90 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67  ns, we are not g
30aa0 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75  oing to tell you
30ab0 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a   what they do..*
30ac0 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
30ad0 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44  _OMIT_DEPRECATED
30ae0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
30af0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  ED int sqlite3_a
30b00 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73  ggregate_count(s
30b10 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
30b20 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
30b30 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
30b40 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f  expired(sqlite3_
30b50 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
30b60 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
30b70 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62  lite3_transfer_b
30b80 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
30b90 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73  stmt*, sqlite3_s
30ba0 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
30bb0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
30bc0 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f  ite3_global_reco
30bd0 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ver(void);.SQLIT
30be0 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
30bf0 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
30c00 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
30c10 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
30c20 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65  D int sqlite3_me
30c30 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28  mory_alarm(void(
30c40 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
30c50 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20  _int64,int),.   
30c60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30c70 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33     void*,sqlite3
30c80 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a  _int64);.#endif.
30c90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30ca0 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46   Obtaining SQL F
30cb0 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65  unction Paramete
30cc0 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54  r Values.**.** T
30cd0 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d  he C-language im
30ce0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
30cf0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
30d00 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65  d aggregates use
30d10 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66  s.** this set of
30d20 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69   interface routi
30d30 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  nes to access th
30d40 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75  e parameter valu
30d50 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e  es on.** the fun
30d60 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
30d70 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  te..**.** The xF
30d80 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20  unc (for scalar 
30d90 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53  functions) or xS
30da0 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61  tep (for aggrega
30db0 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a  tes) parameters.
30dc0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
30dd0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
30de0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
30df0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
30e00 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61  ()].** define ca
30e10 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70  llbacks that imp
30e20 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
30e30 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
30e40 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20  regates..** The 
30e50 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
30e60 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73   these callbacks
30e70 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
30e80 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b  pointers to.** [
30e90 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
30ea0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
30eb0 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20  .  There is one 
30ec0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
30ed0 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61  object for.** ea
30ee0 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ch parameter to 
30ef0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
30f00 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
30f10 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a  s are used to.**
30f20 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20   extract values 
30f30 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
30f40 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
30f50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
30f60 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79  utines work only
30f70 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64   with [protected
30f80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
30f90 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20  objects..** Any 
30fa0 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
30fb0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
30fc0 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64   an [unprotected
30fd0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a   sqlite3_value].
30fe0 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74  ** object result
30ff0 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  s in undefined b
31000 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  ehavior..**.** ^
31010 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
31020 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68  ork just like th
31030 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
31040 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
31050 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63  unctions].** exc
31060 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20  ept that  these 
31070 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20  routines take a 
31080 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65  single [protecte
31090 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
310a0 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74   object.** point
310b0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  er instead of a 
310c0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20  [sqlite3_stmt*] 
310d0 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69  pointer and an i
310e0 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75  nteger column nu
310f0 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mber..**.** ^The
31100 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
31110 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63  ext16() interfac
31120 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46  e extracts a UTF
31130 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  -16 string.** in
31140 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
31150 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
31160 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68  st machine.  ^Th
31170 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  e.** sqlite3_val
31180 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e  ue_text16be() an
31190 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
311a0 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72  text16le() inter
311b0 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74  faces.** extract
311c0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20   UTF-16 strings 
311d0 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e  as big-endian an
311e0 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  d little-endian 
311f0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
31200 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
31210 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
31220 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65  type() interface
31230 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70   attempts to app
31240 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66  ly.** numeric af
31250 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61  finity to the va
31260 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  lue.  This means
31270 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
31280 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63   is.** made to c
31290 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
312a0 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   to an integer o
312b0 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  r floating point
312c0 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20  .  If.** such a 
312d0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f  conversion is po
312e0 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c  ssible without l
312f0 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69  oss of informati
31300 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20  on (in other.** 
31310 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61  words, if the va
31320 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  lue is a string 
31330 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  that looks like 
31340 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65  a number).** the
31350 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  n the conversion
31360 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20   is performed.  
31370 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e  Otherwise no con
31380 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a  version occurs..
31390 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  ** The [SQLITE_I
313a0 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
313b0 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
313c0 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
313d0 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20  )^.**.** Please 
313e0 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61  pay particular a
313f0 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20  ttention to the 
31400 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f  fact that the po
31410 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  inter returned.*
31420 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
31430 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
31440 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
31450 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
31460 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
31470 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
31480 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
31490 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
314a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
314b0 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
314c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
314d0 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
314e0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
314f0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
31500 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a  alue_text16()]..
31510 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
31520 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
31530 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
31540 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
31550 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
31560 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
31570 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
31580 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  *] parameters..*
31590 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
315a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
315b0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
315c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
315d0 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lue_bytes(sqlite
315e0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
315f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
31600 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  es16(sqlite3_val
31610 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  ue*);.double sql
31620 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
31630 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
31640 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
31650 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33  alue_int(sqlite3
31660 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65  _value*);.sqlite
31670 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
31680 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69  value_int64(sqli
31690 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
316a0 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
316b0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
316c0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  text(sqlite3_val
316d0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
316e0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
316f0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76  text16(sqlite3_v
31700 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
31710 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
31720 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  e_text16le(sqlit
31730 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
31740 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
31750 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73  value_text16be(s
31760 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31770 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
31780 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  e_type(sqlite3_v
31790 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
317a0 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
317b0 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  c_type(sqlite3_v
317c0 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
317d0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
317e0 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69  Aggregate Functi
317f0 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  on Context.**.**
31800 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   Implementations
31810 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51   of aggregate SQ
31820 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20  L functions use 
31830 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
31840 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
31850 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74  ry for storing t
31860 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  heir state..**.*
31870 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d  * ^The first tim
31880 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67  e the sqlite3_ag
31890 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
318a0 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20  C,N) routine is 
318b0 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61  called .** for a
318c0 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72   particular aggr
318d0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20  egate function, 
318e0 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61  SQLite.** alloca
318f0 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c  tes N of memory,
31900 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74   zeroes out that
31910 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74   memory, and ret
31920 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  urns a pointer.*
31930 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d  * to the new mem
31940 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20  ory. ^On second 
31950 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63  and subsequent c
31960 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
31970 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
31980 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73  text() for the s
31990 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
319a0 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c  nction instance,
319b0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66  .** the same buf
319c0 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  fer is returned.
319d0 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67    Sqlite3_aggreg
319e0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73  ate_context() is
319f0 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c   normally.** cal
31a00 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  led once for eac
31a10 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  h invocation of 
31a20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61  the xStep callba
31a30 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a  ck and then one.
31a40 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65  ** last time whe
31a50 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c  n the xFinal cal
31a60 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
31a70 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77  .  ^(When no row
31a80 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67  s match.** an ag
31a90 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74  gregate query, t
31aa0 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62  he xStep() callb
31ab0 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65  ack of the aggre
31ac0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  gate function.**
31ad0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
31ae0 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20  is never called 
31af0 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20  and xFinal() is 
31b00 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f  called exactly o
31b10 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65  nce..** In those
31b20 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f   cases, sqlite3_
31b30 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
31b40 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c  t() might be cal
31b50 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66  led for the.** f
31b60 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77  irst time from w
31b70 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29  ithin xFinal().)
31b80 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
31b90 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
31ba0 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
31bb0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55  ine returns a NU
31bc0 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77  LL pointer .** w
31bd0 68 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64  hen first called
31be0 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68   if N is less th
31bf0 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
31c00 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f  ero or if a memo
31c10 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65  ry.** allocate e
31c20 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a  rror occurs..**.
31c30 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20  ** ^(The amount 
31c40 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74  of space allocat
31c50 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67  ed by sqlite3_ag
31c60 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
31c70 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72  C,N) is.** deter
31c80 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70  mined by the N p
31c90 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73  arameter on firs
31ca0 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  t successful cal
31cb0 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65  l.  Changing the
31cc0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69  .** value of N i
31cd0 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
31ce0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67  l to sqlite3_agg
31cf0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
31d00 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73   within.** the s
31d10 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
31d20 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20  nction instance 
31d30 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20  will not resize 
31d40 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  the memory.** al
31d50 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74  location.)^  Wit
31d60 68 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63  hin the xFinal c
31d70 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63  allback, it is c
31d80 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a  ustomary to set.
31d90 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20  ** N=0 in calls 
31da0 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  to sqlite3_aggre
31db0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
31dc0 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a  ) so that no .**
31dd0 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72   pointless memor
31de0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63  y allocations oc
31df0 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  cur..**.** ^SQLi
31e00 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
31e10 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72   frees the memor
31e20 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a  y allocated by .
31e30 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
31e40 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
31e50 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74  hen the aggregat
31e60 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65  e query conclude
31e70 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
31e80 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  st parameter mus
31e90 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74  t be a copy of t
31ea0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
31eb0 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e  ontext | SQL fun
31ec0 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74  ction context] t
31ed0 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74  hat is the first
31ee0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
31ef0 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46   the xStep or xF
31f00 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f  inal callback ro
31f10 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65  utine that imple
31f20 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67  ments the aggreg
31f30 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ate.** function.
31f40 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
31f50 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
31f60 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
31f70 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
31f80 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74  .** the aggregat
31f90 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
31fa0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
31fb0 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72  id *sqlite3_aggr
31fc0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71  egate_context(sq
31fd0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
31fe0 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a  int nBytes);../*
31ff0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73  .** CAPI3REF: Us
32000 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63  er Data For Func
32010 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
32020 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61   sqlite3_user_da
32030 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
32040 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
32050 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
32060 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73  that was the pUs
32070 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72  erData parameter
32080 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65   (the 5th parame
32090 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
320a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
320b0 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
320c0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
320d0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
320e0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
320f0 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
32100 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
32110 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
32120 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
32130 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
32140 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
32150 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
32160 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
32170 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
32180 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
32190 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
321a0 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   *sqlite3_user_d
321b0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
321c0 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
321d0 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
321e0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20   Connection For 
321f0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
32200 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ^The sqlite3_con
32210 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
32220 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
32230 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
32240 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  the pointer to t
32250 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
32260 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73  nection] (the 1s
32270 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  t parameter).** 
32280 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
32290 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
322a0 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
322b0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
322c0 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
322d0 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
322e0 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
322f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
32300 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
32310 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c  .*/.sqlite3 *sql
32320 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
32330 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63  handle(sqlite3_c
32340 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
32350 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
32360 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61  ion Auxiliary Da
32370 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  ta.**.** These f
32380 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
32390 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67  used by (non-agg
323a0 72 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63  regate) SQL func
323b0 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f  tions to.** asso
323c0 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77  ciate metadata w
323d0 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
323e0 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
323f0 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
32400 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
32410 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
32420 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
32430 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
32440 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
32450 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
32460 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
32470 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61  ociated metadata
32480 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65   may be preserve
32490 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a  d.  An example.*
324a0 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69 73 20  * of where this 
324b0 6d 69 67 68 74 20 62 65 20 75 73 65 66 75 6c 20  might be useful 
324c0 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d  is in a regular-
324d0 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
324e0 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ing.** function.
324f0 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65   The compiled ve
32500 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67  rsion of the reg
32510 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
32520 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73  can be stored as
32530 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73  .** metadata ass
32540 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
32550 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e   pattern string.
32560 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f    .** Then as lo
32570 6e 67 20 61 73 20 74 68 65 20 70 61 74 74 65 72  ng as the patter
32580 6e 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73  n string remains
32590 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68   the same,.** th
325a0 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c  e compiled regul
325b0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
325c0 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d  n be reused on m
325d0 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63  ultiple.** invoc
325e0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
325f0 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  me function..**.
32600 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
32610 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
32620 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
32630 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
32640 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
32650 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73  ociated by the s
32660 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
32670 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69  ta() function wi
32680 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  th the Nth argum
32690 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20  ent.** value to 
326a0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
326b0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
326c0 2e 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e  . ^If there is n
326d0 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  o metadata.** as
326e0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
326f0 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  e function argum
32700 65 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65  ent, this sqlite
32710 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
32720 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74  interface.** ret
32730 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
32740 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
32750 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
32760 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74  ata(C,N,P,X) int
32770 65 72 66 61 63 65 20 73 61 76 65 73 20 50 20 61  erface saves P a
32780 73 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74  s metadata for t
32790 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d  he N-th.** argum
327a0 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ent of the appli
327b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
327c0 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65  unction.  ^Subse
327d0 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
327e0 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  o sqlite3_get_au
327f0 78 64 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72  xdata(C,N) retur
32800 6e 20 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73  n P from the mos
32810 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69  t recent.** sqli
32820 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
32830 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66  C,N,P,X) call if
32840 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73   the metadata is
32850 20 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a   still valid or.
32860 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d  ** NULL if the m
32870 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e  etadata has been
32880 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e   discarded..** ^
32890 41 66 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20  After each call 
328a0 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
328b0 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
328c0 77 68 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e  where X is not N
328d0 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ULL,.** SQLite w
328e0 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  ill invoke the d
328f0 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
32900 6f 6e 20 58 20 77 69 74 68 20 70 61 72 61 6d 65  on X with parame
32910 74 65 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a  ter P exactly.**
32920 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20   once, when the 
32930 6d 65 74 61 64 61 74 61 20 69 73 20 64 69 73 63  metadata is disc
32940 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65  arded..** SQLite
32950 20 69 73 20 66 72 65 65 20 74 6f 20 64 69 73 63   is free to disc
32960 61 72 64 20 74 68 65 20 6d 65 74 61 64 61 74 61  ard the metadata
32970 20 61 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e   at any time, in
32980 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a  cluding: <ul>.**
32990 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63   <li> when the c
329a0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e  orresponding fun
329b0 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
329c0 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c  changes, or.** <
329d0 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  li> when [sqlite
329e0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
329f0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
32a00 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72  )] is called for
32a10 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c   the.**      SQL
32a20 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a   statement, or.*
32a30 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69  * <li> when sqli
32a40 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
32a50 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61  ) is invoked aga
32a60 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70  in on the same p
32a70 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20  arameter, or.** 
32a80 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20  <li> during the 
32a90 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33  original sqlite3
32aa0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 63  _set_auxdata() c
32ab0 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72  all when a memor
32ac0 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63  y .**      alloc
32ad0 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
32ae0 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  rs. </ul>)^.**.*
32af0 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20  * Note the last 
32b00 62 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63  bullet in partic
32b10 75 6c 61 72 2e 20 20 54 68 65 20 64 65 73 74 72  ular.  The destr
32b20 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73  uctor X in .** s
32b30 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
32b40 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68  ta(C,N,P,X) migh
32b50 74 20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65  t be called imme
32b60 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20  diately, before 
32b70 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  the.** sqlite3_s
32b80 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
32b90 65 72 66 61 63 65 20 65 76 65 6e 20 72 65 74 75  erface even retu
32ba0 72 6e 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69  rns.  Hence sqli
32bb0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
32bc0 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63  ).** should be c
32bd0 61 6c 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65  alled near the e
32be0 6e 64 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  nd of the functi
32bf0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
32c00 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e  n and the.** fun
32c10 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
32c20 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20  tion should not 
32c30 6d 61 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20  make any use of 
32c40 50 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74  P after.** sqlit
32c50 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
32c60 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64   has been called
32c70 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61  ..**.** ^(In pra
32c80 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20  ctice, metadata 
32c90 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74  is preserved bet
32ca0 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61  ween function ca
32cb0 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74  lls for.** funct
32cc0 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ion parameters t
32cd0 68 61 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d  hat are compile-
32ce0 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20  time constants, 
32cf0 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61  including litera
32d00 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20  l.** values and 
32d10 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64  [parameters] and
32d20 20 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d   expressions com
32d30 70 6f 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73  posed from the s
32d40 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ame.)^.**.** The
32d50 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
32d60 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
32d70 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
32d80 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
32d90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
32da0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
32db0 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   *sqlite3_get_au
32dc0 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
32dd0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  ntext*, int N);.
32de0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74  void sqlite3_set
32df0 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
32e00 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
32e10 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a  , void*, void (*
32e20 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a  )(void*));.../*.
32e30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
32e40 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20  stants Defining 
32e50 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74  Special Destruct
32e60 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a  or Behavior.**.*
32e70 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63  * These are spec
32e80 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74  ial values for t
32e90 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68  he destructor th
32ea0 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20  at is passed in 
32eb0 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  as the.** final 
32ec0 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74  argument to rout
32ed0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
32ee0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
32ef0 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74  ].  ^If the dest
32f00 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65  ructor.** argume
32f10 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41  nt is SQLITE_STA
32f20 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  TIC, it means th
32f30 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70  at the content p
32f40 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61  ointer is consta
32f50 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e  nt.** and will n
32f60 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74  ever change.  It
32f70 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
32f80 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20  o be destroyed. 
32f90 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f   ^The.** SQLITE_
32fa0 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20  TRANSIENT value 
32fb0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
32fc0 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65  ontent will like
32fd0 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ly change in.** 
32fe0 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20  the near future 
32ff0 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20  and that SQLite 
33000 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20  should make its 
33010 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
33020 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
33030 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  nt before return
33040 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ing..**.** The t
33050 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73  ypedef is necess
33060 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  ary to work arou
33070 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63  nd problems in c
33080 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f  ertain.** C++ co
33090 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65  mpilers..*/.type
330a0 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
330b0 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
330c0 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66  pe)(void*);.#def
330d0 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ine SQLITE_STATI
330e0 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33  C      ((sqlite3
330f0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
33100 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  )0).#define SQLI
33110 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28  TE_TRANSIENT   (
33120 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
33130 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a  tor_type)-1)../*
33140 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
33150 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74  tting The Result
33160 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74   Of An SQL Funct
33170 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ion.**.** These 
33180 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
33190 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f  d by the xFunc o
331a0 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
331b0 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65  ks that.** imple
331c0 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  ment SQL functio
331d0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
331e0 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69  s.  See.** [sqli
331f0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
33200 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
33210 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
33220 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20  ion16()].** for 
33230 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
33240 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
33250 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f  ese functions wo
33260 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b  rk very much lik
33270 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72  e the [parameter
33280 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79   binding] family
33290 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   of.** functions
332a0 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61   used to bind va
332b0 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
332c0 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61  ameters in prepa
332d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  red statements..
332e0 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20  ** Refer to the 
332f0 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
33300 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
33310 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
33320 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
33330 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
33340 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72  ult_blob() inter
33350 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
33360 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
33370 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
33380 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
33390 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73  be the BLOB whos
333a0 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69  e content is poi
333b0 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68  nted.** to by th
333c0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
333d0 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20  er and which is 
333e0 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65  N bytes long whe
333f0 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74  re N is the.** t
33400 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a  hird parameter..
33410 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33420 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
33430 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  ob() interfaces 
33440 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f  set the result o
33450 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
33460 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
33470 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c  ction to be a BL
33480 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c  OB containing al
33490 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20  l zero.** bytes 
334a0 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73  and N bytes in s
334b0 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ize, where N is 
334c0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
334d0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a   2nd parameter..
334e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
334f0 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
33500 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
33510 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
33520 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
33530 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
33540 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f  tion to be a flo
33550 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
33560 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
33570 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  y its 2nd argume
33580 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
33590 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
335a0 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
335b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
335c0 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  () functions.** 
335d0 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d  cause the implem
335e0 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69  ented SQL functi
335f0 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  on to throw an e
33600 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51  xception..** ^SQ
33610 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74  Lite uses the st
33620 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20  ring pointed to 
33630 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61  by the.** 2nd pa
33640 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74  rameter of sqlit
33650 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
33660 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  ) or sqlite3_res
33670 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
33680 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20   as the text of 
33690 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
336a0 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72  .  ^SQLite inter
336b0 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a  prets the error.
336c0 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  ** message strin
336d0 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
336e0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73  esult_error() as
336f0 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a   UTF-8. ^SQLite.
33700 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  ** interprets th
33710 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
33720 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33730 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36  or16() as UTF-16
33740 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79   in native.** by
33750 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74  te order.  ^If t
33760 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
33770 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
33780 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
33790 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
337a0 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e  t_error16() is n
337b0 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
337c0 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65  ite takes as the
337d0 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
337e0 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68  e all text up th
337f0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
33800 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
33810 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  ** ^If the third
33820 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
33830 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33840 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  or() or.** sqlit
33850 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
33860 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  6() is non-negat
33870 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
33880 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a  takes that many.
33890 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ** bytes (not ch
338a0 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74  aracters) from t
338b0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
338c0 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65   as the error me
338d0 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73  ssage..** ^The s
338e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
338f0 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
33900 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
33910 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d  ().** routines m
33920 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f  ake a private co
33930 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  py of the error 
33940 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66  message text bef
33950 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75  ore.** they retu
33960 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  rn.  Hence, the 
33970 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
33980 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20   can deallocate 
33990 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65  or.** modify the
339a0 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79   text after they
339b0 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20   return without 
339c0 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  harm..** ^The sq
339d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
339e0 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69  or_code() functi
339f0 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65  on changes the e
33a00 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74  rror code.** ret
33a10 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20  urned by SQLite 
33a20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61  as a result of a
33a30 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e  n error in a fun
33a40 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61  ction.  ^By defa
33a50 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f  ult,.** the erro
33a60 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45  r code is SQLITE
33a70 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73  _ERROR.  ^A subs
33a80 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73  equent call to s
33a90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33aa0 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
33ab0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33ac0 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20  16() resets the 
33ad0 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51  error code to SQ
33ae0 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a  LITE_ERROR..**.*
33af0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
33b00 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
33b10 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  ig() interface c
33b20 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
33b30 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f  throw an.** erro
33b40 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  r indicating tha
33b50 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  t a string or BL
33b60 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74  OB is too long t
33b70 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a  o represent..**.
33b80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33b90 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d  result_error_nom
33ba0 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  em() interface c
33bb0 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
33bc0 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f  throw an.** erro
33bd0 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  r indicating tha
33be0 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  t a memory alloc
33bf0 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a  ation failed..**
33c00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33c10 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e  _result_int() in
33c20 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
33c30 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
33c40 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
33c50 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
33c60 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33  tion to be the 3
33c70 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  2-bit signed int
33c80 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
33c90 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
33ca0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
33cb0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33cc0 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63  int64() interfac
33cd0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
33ce0 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
33cf0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
33d00 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
33d10 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20  o be the 64-bit 
33d20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
33d30 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
33d40 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
33d50 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
33d60 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
33d70 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  l() interface se
33d80 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
33d90 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
33da0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
33db0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
33dc0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
33dd0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
33de0 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33  _text(), sqlite3
33df0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29  _result_text16()
33e00 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  ,.** sqlite3_res
33e10 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20  ult_text16le(), 
33e20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
33e30 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e  lt_text16be() in
33e40 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20  terfaces.** set 
33e50 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
33e60 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
33e70 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
33e80 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20  tion to be.** a 
33e90 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63  text string whic
33ea0 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  h is represented
33eb0 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31   as UTF-8, UTF-1
33ec0 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
33ed0 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c  der,.** UTF-16 l
33ee0 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72  ittle endian, or
33ef0 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69   UTF-16 big endi
33f00 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  an, respectively
33f10 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b  ..** ^SQLite tak
33f20 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75  es the text resu
33f30 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c  lt from the appl
33f40 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20  ication from.** 
33f50 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
33f60 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
33f70 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
33f80 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66  terfaces..** ^If
33f90 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
33fa0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
33fb0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
33fc0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
33fd0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53  negative, then S
33fe0 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75  QLite takes resu
33ff0 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65  lt text from the
34000 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a   2nd parameter.*
34010 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  * through the fi
34020 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
34030 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  er..** ^If the 3
34040 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
34050 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
34060 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
34070 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65  ces.** is non-ne
34080 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20  gative, then as 
34090 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20  many bytes (not 
340a0 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74  characters) of t
340b0 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74  he text.** point
340c0 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64  ed to by the 2nd
340d0 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74   parameter are t
340e0 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c  aken as the appl
340f0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a  ication-defined.
34100 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75  ** function resu
34110 6c 74 2e 20 20 49 66 20 74 68 65 20 33 72 64 20  lt.  If the 3rd 
34120 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e  parameter is non
34130 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
34140 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68  it.** must be th
34150 65 20 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e  e byte offset in
34160 74 6f 20 74 68 65 20 73 74 72 69 6e 67 20 77 68  to the string wh
34170 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d  ere the NUL term
34180 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20  inator would.** 
34190 61 70 70 65 61 72 20 69 66 20 74 68 65 20 73 74  appear if the st
341a0 72 69 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74  ring where NUL t
341b0 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61  erminated.  If a
341c0 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72  ny NUL character
341d0 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  s occur.** in th
341e0 65 20 73 74 72 69 6e 67 20 61 74 20 61 20 62 79  e string at a by
341f0 74 65 20 6f 66 66 73 65 74 20 74 68 61 74 20 69  te offset that i
34200 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20  s less than the 
34210 76 61 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64  value of the 3rd
34220 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74  .** parameter, t
34230 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e  hen the resultin
34240 67 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f  g string will co
34250 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e  ntain embedded N
34260 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72  ULs and the.** r
34270 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73  esult of express
34280 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f  ions operating o
34290 6e 20 73 74 72 69 6e 67 73 20 77 69 74 68 20 65  n strings with e
342a0 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20  mbedded NULs is 
342b0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49  undefined..** ^I
342c0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
342d0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
342e0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
342f0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
34300 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34310 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55  blob is a non-NU
34320 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
34330 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68   SQLite calls th
34340 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61  at.** function a
34350 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  s the destructor
34360 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20   on the text or 
34370 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e  BLOB result when
34380 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73   it has.** finis
34390 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
343a0 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
343b0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
343c0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
343d0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
343e0 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20  rfaces or to.** 
343f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
34400 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
34410 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
34420 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20  TE_STATIC, then 
34430 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65  SQLite.** assume
34440 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20  s that the text 
34450 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69  or BLOB result i
34460 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70  s in constant sp
34470 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
34480 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e  .** copy the con
34490 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61  tent of the para
344a0 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61  meter nor call a
344b0 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
344c0 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68  he content.** wh
344d0 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  en it has finish
344e0 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
344f0 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  sult..** ^If the
34500 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
34510 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
34520 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
34530 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
34540 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
34550 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
34560 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54  onstant SQLITE_T
34570 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e  RANSIENT.** then
34580 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20   SQLite makes a 
34590 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75  copy of the resu
345a0 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62  lt into space ob
345b0 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66  tained from.** f
345c0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
345d0 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74  loc()] before it
345e0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
345f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
34600 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
34610 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
34620 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
34630 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
34640 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
34650 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a  be a copy the.**
34660 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
34670 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
34680 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79  ect specified by
34690 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
346a0 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  er.  ^The.** sql
346b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
346c0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61  e() interface ma
346d0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
346e0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
346f0 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65  ].** so that the
34700 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
34710 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68   specified in th
34720 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
34730 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20  change or.** be 
34740 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65  deallocated afte
34750 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
34760 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73  _value() returns
34770 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
34780 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20  * ^A [protected 
34790 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
347a0 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73  bject may always
347b0 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61   be used where a
347c0 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
347d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
347e0 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69   object is requi
347f0 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a  red, so either.*
34800 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74  * kind of [sqlit
34810 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
34820 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74   can be used wit
34830 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  h this interface
34840 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65  ..**.** If these
34850 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
34860 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e  lled from within
34870 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74   the different t
34880 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68  hread.** than th
34890 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67  e one containing
348a0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
348b0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
348c0 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a  n that received.
348d0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
348e0 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72  context] pointer
348f0 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
34900 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
34910 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
34920 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ult_blob(sqlite3
34930 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
34940 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
34950 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
34960 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
34970 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
34980 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
34990 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  e);.void sqlite3
349a0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
349b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
349c0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
349d0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
349e0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
349f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
34a00 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
34a10 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
34a20 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
34a30 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e  obig(sqlite3_con
34a40 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
34a50 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34a60 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f  r_nomem(sqlite3_
34a70 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
34a80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34a90 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65  rror_code(sqlite
34aa0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
34ab0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
34ac0 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65  esult_int(sqlite
34ad0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
34ae0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
34af0 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69  esult_int64(sqli
34b00 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
34b10 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f  lite3_int64);.vo
34b20 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
34b30 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63  t_null(sqlite3_c
34b40 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
34b50 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
34b60 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
34b70 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
34b80 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
34b90 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
34ba0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
34bb0 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
34bc0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
34bd0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
34be0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
34bf0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
34c00 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16le(sqlite3_con
34c10 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
34c20 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
34c30 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
34c40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
34c50 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
34c60 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
34c70 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
34c80 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
34c90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
34ca0 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lue(sqlite3_cont
34cb0 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61  ext*, sqlite3_va
34cc0 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  lue*);.void sqli
34cd0 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
34ce0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
34cf0 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f  ext*, int n);../
34d00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
34d10 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74  efine New Collat
34d20 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a  ing Sequences.**
34d30 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
34d40 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65  ions add, remove
34d50 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63  , or modify a [c
34d60 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69  ollation] associ
34d70 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ated.** with the
34d80 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
34d90 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
34da0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
34db0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
34dc0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
34dd0 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54  ollation is a UT
34de0 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f  F-8 string.** fo
34df0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
34e00 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64  _collation() and
34e10 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
34e20 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a  collation_v2().*
34e30 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73  * and a UTF-16 s
34e40 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
34e50 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73  byte order for s
34e60 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
34e70 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20  llation16()..** 
34e80 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73  ^Collation names
34e90 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71   that compare eq
34ea0 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  ual according to
34eb0 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63   [sqlite3_strnic
34ec0 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e  mp()] are.** con
34ed0 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 74 68  sidered to be th
34ee0 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a  e same name..**.
34ef0 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20 61  ** ^(The third a
34f00 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65  rgument (eTextRe
34f10 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f  p) must be one o
34f20 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a  f the constants:
34f30 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
34f40 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a   [SQLITE_UTF8],.
34f50 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
34f60 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69  UTF16LE],.** <li
34f70 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  > [SQLITE_UTF16B
34f80 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
34f90 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a  ITE_UTF16], or.*
34fa0 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
34fb0 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a  TF16_ALIGNED]..*
34fc0 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68  * </ul>)^.** ^Th
34fd0 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d  e eTextRep argum
34fe0 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ent determines t
34ff0 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73  he encoding of s
35000 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a  trings passed.**
35010 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
35020 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
35030 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a  ack, xCallback..
35040 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
35050 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49  UTF16] and [SQLI
35060 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
35070 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65  ] values for eTe
35080 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73  xtRep.** force s
35090 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46  trings to be UTF
350a0 31 36 20 77 69 74 68 20 6e 61 74 69 76 65 20 62  16 with native b
350b0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54  yte order..** ^T
350c0 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  he [SQLITE_UTF16
350d0 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20  _ALIGNED] value 
350e0 66 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f 72  for eTextRep for
350f0 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62  ces strings to b
35100 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76  egin.** on an ev
35110 65 6e 20 62 79 74 65 20 61 64 64 72 65 73 73 2e  en byte address.
35120 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
35130 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72  th argument, pAr
35140 67 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61  g, is an applica
35150 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
35160 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
35170 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74  .** through as t
35180 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
35190 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  t to the collati
351a0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  ng function call
351b0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  back..**.** ^The
351c0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c   fifth argument,
351d0 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61   xCallback, is a
351e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
351f0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
35200 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65  on..** ^Multiple
35210 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
35220 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69  ions can be regi
35230 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
35240 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a   same name but.*
35250 2a 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  * with different
35260 20 65 54 65 78 74 52 65 70 20 70 61 72 61 6d 65   eTextRep parame
35270 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20  ters and SQLite 
35280 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76  will use whichev
35290 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72  er.** function r
352a0 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73  equires the leas
352b0 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
352c0 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e   transformation.
352d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c  .** ^If the xCal
352e0 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69  lback argument i
352f0 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20  s NULL then the 
35300 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
35310 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64  on is.** deleted
35320 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c  .  ^When all col
35330 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
35340 20 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65   having the same
35350 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65   name are delete
35360 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61  d,.** that colla
35370 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  tion is no longe
35380 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  r usable..**.** 
35390 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66  ^The collating f
353a0 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
353b0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
353c0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70   a copy of the p
353d0 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74  Arg .** applicat
353e0 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
353f0 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74   and with two st
35400 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63  rings in the enc
35410 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a  oding specified.
35420 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78 74 52  ** by the eTextR
35430 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68  ep argument.  Th
35440 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
35450 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e  tion must return
35460 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74   an.** integer t
35470 68 61 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c  hat is negative,
35480 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69   zero, or positi
35490 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72  ve.** if the fir
354a0 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73  st string is les
354b0 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f  s than, equal to
354c0 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  , or greater tha
354d0 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a  n the second,.**
354e0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20   respectively.  
354f0 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  A collating func
35500 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73  tion must always
35510 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65   return the same
35520 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e   answer.** given
35530 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73   the same inputs
35540 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  .  If two or mor
35550 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
35560 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74  tions are regist
35570 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73  ered.** to the s
35580 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61  ame collation na
35590 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66 65 72  me (using differ
355a0 65 6e 74 20 65 54 65 78 74 52 65 70 20 76 61 6c  ent eTextRep val
355b0 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a  ues) then all.**
355c0 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65 71   must give an eq
355d0 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20  uivalent answer 
355e0 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74  when invoked wit
355f0 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72  h equivalent str
35600 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c  ings..** The col
35610 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
35620 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f  must obey the fo
35630 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69  llowing properti
35640 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74  es for all.** st
35650 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20  rings A, B, and 
35660 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  C:.**.** <ol>.**
35670 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68   <li> If A==B th
35680 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e  en B==A..** <li>
35690 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d   If A==B and B==
356a0 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20  C then A==C..** 
356b0 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54  <li> If A&lt;B T
356c0 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c  HEN B&gt;A..** <
356d0 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e  li> If A&lt;B an
356e0 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26  d B&lt;C then A&
356f0 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  lt;C..** </ol>.*
35700 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74  *.** If a collat
35710 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69  ing function fai
35720 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62  ls any of the ab
35730 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  ove constraints 
35740 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c  and that.** coll
35750 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
35760 73 20 20 72 65 67 69 73 74 65 72 65 64 20 61 6e  s  registered an
35770 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65  d used, then the
35780 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
35790 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ite.** is undefi
357a0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
357b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
357c0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f  ollation_v2() wo
357d0 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
357e0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
357f0 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  n().** with the 
35800 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68  addition that th
35810 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62  e xDestroy callb
35820 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
35830 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74  n pArg when.** t
35840 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
35850 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
35860 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20  ..** ^Collating 
35870 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65  functions are de
35880 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 79 20  leted when they 
35890 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62  are overridden b
358a0 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73  y later.** calls
358b0 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   to the collatio
358c0 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74  n creation funct
358d0 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65  ions or when the
358e0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
358f0 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f  nnection] is clo
35900 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  sed using [sqlit
35910 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a  e3_close()]..**.
35920 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79  ** ^The xDestroy
35930 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e   callback is <u>
35940 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69  not</u> called i
35950 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65  f the .** sqlite
35960 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
35970 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e  on_v2() function
35980 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61   fails.  Applica
35990 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b  tions that invok
359a0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65  e.** sqlite3_cre
359b0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
359c0 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  () with a non-NU
359d0 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67 75  LL xDestroy argu
359e0 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20  ment should .** 
359f0 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
35a00 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73   code and dispos
35a10 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  e of the applica
35a20 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
35a30 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20  r.** themselves 
35a40 72 61 74 68 65 72 20 74 68 61 6e 20 65 78 70 65  rather than expe
35a50 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20  cting SQLite to 
35a60 64 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72  deal with it for
35a70 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69   them..** This i
35a80 73 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  s different from
35a90 20 65 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c   every other SQL
35aa0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
35ab0 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63  The inconsistenc
35ac0 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75  y .** is unfortu
35ad0 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20  nate but cannot 
35ae0 62 65 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f  be changed witho
35af0 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b  ut breaking back
35b00 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74  wards .** compat
35b10 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53  ibility..**.** S
35b20 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74  ee also:  [sqlit
35b30 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
35b40 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ded()] and [sqli
35b50 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
35b60 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e  eded16()]..*/.in
35b70 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
35b80 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71  _collation(.  sq
35b90 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
35ba0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
35bb0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
35bc0 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
35bd0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
35be0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
35bf0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
35c00 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
35c10 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
35c20 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ation_v2(.  sqli
35c30 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
35c40 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
35c50 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
35c60 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
35c70 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
35c80 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
35c90 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
35ca0 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  d*),.  void(*xDe
35cb0 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
35cc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
35cd0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
35ce0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
35cf0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d  const void *zNam
35d00 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  e,.  int eTextRe
35d10 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67  p, .  void *pArg
35d20 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
35d30 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
35d40 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
35d50 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  st void*).);../*
35d60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
35d70 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43  llation Needed C
35d80 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
35d90 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20  To avoid having 
35da0 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20  to register all 
35db0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
35dc0 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74  ces before a dat
35dd0 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20  abase.** can be 
35de0 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63  used, a single c
35df0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
35e00 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72   may be register
35e10 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
35e20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35e30 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b  ion] to be invok
35e40 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75  ed whenever an u
35e50 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
35e60 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69  on.** sequence i
35e70 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  s required..**.*
35e80 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  * ^If the functi
35e90 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64  on is registered
35ea0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
35eb0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
35ec0 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68  ded() API,.** th
35ed0 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20  en it is passed 
35ee0 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64  the names of und
35ef0 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
35f00 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74   sequences as st
35f10 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64  rings.** encoded
35f20 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73   in UTF-8. ^If s
35f30 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
35f40 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75  _needed16() is u
35f50 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  sed,.** the name
35f60 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  s are passed as 
35f70 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e  UTF-16 in machin
35f80 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
35f90 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  der..** ^A call 
35fa0 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69  to either functi
35fb0 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20  on replaces the 
35fc0 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69  existing collati
35fd0 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61  on-needed callba
35fe0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e  ck..**.** ^(When
35ff0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
36000 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69   invoked, the fi
36010 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73  rst argument pas
36020 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a  sed is a copy.**
36030 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
36040 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
36050 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
36060 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ded() or.** sqli
36070 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
36080 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73  eded16().  The s
36090 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
360a0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  s the database.*
360b0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  * connection.  T
360c0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
360d0 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
360e0 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
360f0 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
36100 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
36110 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  LE], indicating 
36120 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62  the most desirab
36130 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63  le form of the c
36140 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
36150 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65  ence function re
36160 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75  quired.  The fou
36170 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
36180 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
36190 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c  .** required col
361a0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e  lation sequence.
361b0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  )^.**.** The cal
361c0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73  lback function s
361d0 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74  hould register t
361e0 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61  he desired colla
361f0 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
36200 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36210 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c  llation()], [sql
36220 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36230 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  ation16()], or.*
36240 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
36250 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
36260 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
36270 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
36280 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ed(.  sqlite3*, 
36290 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69  .  void*, .  voi
362a0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
362b0 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
362c0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b  ,const char*).);
362d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
362e0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
362f0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
36300 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29  void*,.  void(*)
36310 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
36320 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
36330 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69  st void*).);..#i
36340 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f  fdef SQLITE_HAS_
36350 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63  CODEC./*.** Spec
36360 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20  ify the key for 
36370 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74  an encrypted dat
36380 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75  abase.  This rou
36390 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  tine should be.*
363a0 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61  * called right a
363b0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  fter sqlite3_ope
363c0 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  n()..**.** The c
363d0 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
363e0 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
363f0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
36400 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
36410 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
36420 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65  /.int sqlite3_ke
36430 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
36440 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
36450 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
36460 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
36470 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
36480 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
36490 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a    /* The key */.
364a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b  );.int sqlite3_k
364b0 65 79 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  ey_v2(.  sqlite3
364c0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
364d0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
364e0 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
364f0 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  d */.  const cha
36500 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20  r *zDbName,     
36510 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
36520 20 74 68 65 20 64 61 74 61 62 61 73 65 20 2a 2f   the database */
36530 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
36540 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
36550 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a    /* The key */.
36560 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65  );../*.** Change
36570 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f   the key on an o
36580 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49  pen database.  I
36590 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  f the current da
365a0 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a  tabase is not.**
365b0 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73   encrypted, this
365c0 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e   routine will en
365d0 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e  crypt it.  If pN
365e0 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30  ew==0 or nNew==0
365f0 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  , the.** databas
36600 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a  e is decrypted..
36610 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
36620 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
36630 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
36640 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
36650 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
36660 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
36670 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a   sqlite3_rekey(.
36680 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
36690 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
366a0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
366b0 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
366c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
366d0 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
366e0 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f  * The new key */
366f0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
36700 72 65 6b 65 79 5f 76 32 28 0a 20 20 73 71 6c 69  rekey_v2(.  sqli
36710 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
36720 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
36730 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
36740 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
36750 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20  char *zDbName,  
36760 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65           /* Name
36770 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
36780 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
36790 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
367a0 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20       /* The new 
367b0 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
367c0 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74   Specify the act
367d0 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20  ivation key for 
367e0 61 20 53 45 45 20 64 61 74 61 62 61 73 65 2e 20  a SEE database. 
367f0 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69   Unless .** acti
36800 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74  vated, none of t
36810 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20  he SEE routines 
36820 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f  will work..*/.vo
36830 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76  id sqlite3_activ
36840 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74  ate_see(.  const
36850 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61   char *zPassPhra
36860 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74  se        /* Act
36870 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a  ivation phrase *
36880 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66  /.);.#endif..#if
36890 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c  def SQLITE_ENABL
368a0 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70  E_CEROD./*.** Sp
368b0 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61  ecify the activa
368c0 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43  tion key for a C
368d0 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20  EROD database.  
368e0 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76  Unless .** activ
368f0 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68  ated, none of th
36900 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73  e CEROD routines
36910 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76   will work..*/.v
36920 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69  oid sqlite3_acti
36930 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f  vate_cerod(.  co
36940 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50  nst char *zPassP
36950 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20  hrase        /* 
36960 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73  Activation phras
36970 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a  e */.);.#endif..
36980 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36990 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f  Suspend Executio
369a0 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69  n For A Short Ti
369b0 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  me.**.** The sql
369c0 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e  ite3_sleep() fun
369d0 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65  ction causes the
369e0 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20   current thread 
369f0 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75  to suspend execu
36a00 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c  tion.** for at l
36a10 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66  east a number of
36a20 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70   milliseconds sp
36a30 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70  ecified in its p
36a40 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
36a50 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  If the operating
36a60 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74   system does not
36a70 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72   support sleep r
36a80 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20  equests with.** 
36a90 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65  millisecond time
36aa0 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65   resolution, the
36ab0 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20  n the time will 
36ac0 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f  be rounded up to
36ad0 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20  .** the nearest 
36ae0 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62  second. The numb
36af0 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
36b00 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75  ds of sleep actu
36b10 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65  ally.** requeste
36b20 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61  d from the opera
36b30 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72  ting system is r
36b40 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
36b50 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74  SQLite implement
36b60 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  s this interface
36b70 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20   by calling the 
36b80 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68  xSleep().** meth
36b90 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
36ba0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
36bb0 6f 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20  object.  If the 
36bc0 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a  xSleep() method.
36bd0 2a 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  ** of the defaul
36be0 74 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70  t VFS is not imp
36bf0 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74  lemented correct
36c00 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65  ly, or not imple
36c10 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c  mented at.** all
36c20 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
36c30 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ior of sqlite3_s
36c40 6c 65 65 70 28 29 20 6d 61 79 20 64 65 76 69 61  leep() may devia
36c50 74 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63  te from the desc
36c60 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68  ription.** in th
36c70 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67  e previous parag
36c80 72 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  raphs..*/.int sq
36c90 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29  lite3_sleep(int)
36ca0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36cb0 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46  F: Name Of The F
36cc0 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65  older Holding Te
36cd0 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a  mporary Files.**
36ce0 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c  .** ^(If this gl
36cf0 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73  obal variable is
36d00 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
36d10 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
36d20 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20   is.** the name 
36d30 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b  of a folder (a.k
36d40 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20  .a. directory), 
36d50 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61  then all tempora
36d60 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61  ry files.** crea
36d70 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 68  ted by SQLite wh
36d80 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74  en using a built
36d90 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  -in [sqlite3_vfs
36da0 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20   | VFS].** will 
36db0 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61  be placed in tha
36dc0 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20  t directory.)^  
36dd0 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c  ^If this variabl
36de0 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  e.** is a NULL p
36df0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
36e00 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73  ite performs a s
36e10 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70  earch for an app
36e20 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70  ropriate.** temp
36e30 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63  orary file direc
36e40 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69  tory..**.** It i
36e50 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65  s not safe to re
36e60 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ad or modify thi
36e70 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f  s variable in mo
36e80 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74  re than one.** t
36e90 68 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e  hread at a time.
36ea0 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65    It is not safe
36eb0 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69   to read or modi
36ec0 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
36ed0 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61  .** if a [databa
36ee0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
36ef0 73 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20  s being used at 
36f00 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e  the same time in
36f10 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74   a separate.** t
36f20 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20  hread..** It is 
36f30 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68  intended that th
36f40 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73  is variable be s
36f50 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61  et once.** as pa
36f60 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e  rt of process in
36f70 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
36f80 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69   before any SQLi
36f90 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  te interface.** 
36fa0 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65  routines have be
36fb0 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68  en called and th
36fc0 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
36fd0 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65   remain unchange
36fe0 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e  d.** thereafter.
36ff0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d  .**.** ^The [tem
37000 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
37010 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f  y pragma] may mo
37020 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
37030 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20  le and cause.** 
37040 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  it to point to m
37050 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
37060 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
37070 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d  loc].  ^Furtherm
37080 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d  ore,.** the [tem
37090 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
370a0 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73  y pragma] always
370b0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e   assumes that an
370c0 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74  y string.** that
370d0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70   this variable p
370e0 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64  oints to is held
370f0 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   in memory obtai
37100 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71  ned from .** [sq
37110 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e  lite3_malloc] an
37120 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79  d the pragma may
37130 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65   attempt to free
37140 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20   that memory.** 
37150 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
37160 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20  ree]..** Hence, 
37170 69 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  if this variable
37180 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72   is modified dir
37190 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74  ectly, either it
371a0 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61   should be.** ma
371b0 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20  de NULL or made 
371c0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f  to point to memo
371d0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
371e0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
371f0 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65  ].** or else the
37200 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d   use of the [tem
37210 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
37220 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64  y pragma] should
37230 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 0a   be avoided..**.
37240 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
37250 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73  ndows Runtime us
37260 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65  ers:</b>  The te
37270 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72  mporary director
37280 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a  y must be set.**
37290 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
372a0 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5d  g [sqlite3_open]
372b0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
372c0 6e 5f 76 32 5d 2e 20 20 4f 74 68 65 72 77 69 73  n_v2].  Otherwis
372d0 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65  e, various.** fe
372e0 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75  atures that requ
372f0 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  ire the use of t
37300 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d  emporary files m
37310 61 79 20 66 61 69 6c 2e 20 20 48 65 72 65 20 69  ay fail.  Here i
37320 73 20 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65 20  s an.** example 
37330 6f 66 20 68 6f 77 20 74 6f 20 64 6f 20 74 68 69  of how to do thi
37340 73 20 75 73 69 6e 67 20 43 2b 2b 20 77 69 74 68  s using C++ with
37350 20 74 68 65 20 57 69 6e 64 6f 77 73 20 52 75 6e   the Windows Run
37360 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  time:.**.** <blo
37370 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
37380 20 4c 50 43 57 53 54 52 20 7a 50 61 74 68 20 3d   LPCWSTR zPath =
37390 20 57 69 6e 64 6f 77 73 3a 3a 53 74 6f 72 61 67   Windows::Storag
373a0 65 3a 3a 41 70 70 6c 69 63 61 74 69 6f 6e 44 61  e::ApplicationDa
373b0 74 61 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a 2a  ta::Current->.**
373c0 20 26 6e 62 73 70 3b 20 20 20 20 20 54 65 6d 70   &nbsp;     Temp
373d0 6f 72 61 72 79 46 6f 6c 64 65 72 2d 3e 50 61 74  oraryFolder->Pat
373e0 68 2d 3e 44 61 74 61 28 29 3b 0a 2a 2a 20 63 68  h->Data();.** ch
373f0 61 72 20 7a 50 61 74 68 42 75 66 26 23 39 31 3b  ar zPathBuf&#91;
37400 4d 41 58 5f 50 41 54 48 20 2b 20 31 26 23 39 33  MAX_PATH + 1&#93
37410 3b 3b 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a 50 61  ;;.** memset(zPa
37420 74 68 42 75 66 2c 20 30 2c 20 73 69 7a 65 6f 66  thBuf, 0, sizeof
37430 28 7a 50 61 74 68 42 75 66 29 29 3b 0a 2a 2a 20  (zPathBuf));.** 
37440 57 69 64 65 43 68 61 72 54 6f 4d 75 6c 74 69 42  WideCharToMultiB
37450 79 74 65 28 43 50 5f 55 54 46 38 2c 20 30 2c 20  yte(CP_UTF8, 0, 
37460 7a 50 61 74 68 2c 20 2d 31 2c 20 7a 50 61 74 68  zPath, -1, zPath
37470 42 75 66 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74  Buf, sizeof(zPat
37480 68 42 75 66 29 2c 0a 2a 2a 20 26 6e 62 73 70 3b  hBuf),.** &nbsp;
37490 20 20 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c 4c 29       NULL, NULL)
374a0 3b 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 65 6d  ;.** sqlite3_tem
374b0 70 5f 64 69 72 65 63 74 6f 72 79 20 3d 20 73 71  p_directory = sq
374c0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 25  lite3_mprintf("%
374d0 73 22 2c 20 7a 50 61 74 68 42 75 66 29 3b 0a 2a  s", zPathBuf);.*
374e0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
374f0 75 6f 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  uote>.*/.SQLITE_
37500 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c  EXTERN char *sql
37510 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
37520 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ory;../*.** CAPI
37530 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68  3REF: Name Of Th
37540 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67  e Folder Holding
37550 20 44 61 74 61 62 61 73 65 20 46 69 6c 65 73 0a   Database Files.
37560 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20  **.** ^(If this 
37570 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20  global variable 
37580 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
37590 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69   to a string whi
375a0 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  ch is.** the nam
375b0 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61  e of a folder (a
375c0 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29  .k.a. directory)
375d0 2c 20 74 68 65 6e 20 61 6c 6c 20 64 61 74 61 62  , then all datab
375e0 61 73 65 20 66 69 6c 65 73 0a 2a 2a 20 73 70 65  ase files.** spe
375f0 63 69 66 69 65 64 20 77 69 74 68 20 61 20 72 65  cified with a re
37600 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65 20  lative pathname 
37610 61 6e 64 20 63 72 65 61 74 65 64 20 6f 72 20 61  and created or a
37620 63 63 65 73 73 65 64 20 62 79 0a 2a 2a 20 53 51  ccessed by.** SQ
37630 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20  Lite when using 
37640 61 20 62 75 69 6c 74 2d 69 6e 20 77 69 6e 64 6f  a built-in windo
37650 77 73 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  ws [sqlite3_vfs 
37660 7c 20 56 46 53 5d 20 77 69 6c 6c 20 62 65 20 61  | VFS] will be a
37670 73 73 75 6d 65 64 0a 2a 2a 20 74 6f 20 62 65 20  ssumed.** to be 
37680 72 65 6c 61 74 69 76 65 20 74 6f 20 74 68 61 74  relative to that
37690 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 5e 49   directory.)^ ^I
376a0 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
376b0 69 73 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  is a NULL.** poi
376c0 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
376d0 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61  e assumes that a
376e0 6c 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ll database file
376f0 73 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 77  s specified.** w
37700 69 74 68 20 61 20 72 65 6c 61 74 69 76 65 20 70  ith a relative p
37710 61 74 68 6e 61 6d 65 20 61 72 65 20 72 65 6c 61  athname are rela
37720 74 69 76 65 20 74 6f 20 74 68 65 20 63 75 72 72  tive to the curr
37730 65 6e 74 20 64 69 72 65 63 74 6f 72 79 0a 2a 2a  ent directory.**
37740 20 66 6f 72 20 74 68 65 20 70 72 6f 63 65 73 73   for the process
37750 2e 20 20 4f 6e 6c 79 20 74 68 65 20 77 69 6e 64  .  Only the wind
37760 6f 77 73 20 56 46 53 20 6d 61 6b 65 73 20 75 73  ows VFS makes us
37770 65 20 6f 66 20 74 68 69 73 20 67 6c 6f 62 61 6c  e of this global
37780 0a 2a 2a 20 76 61 72 69 61 62 6c 65 3b 20 69 74  .** variable; it
37790 20 69 73 20 69 67 6e 6f 72 65 64 20 62 79 20 74   is ignored by t
377a0 68 65 20 75 6e 69 78 20 56 46 53 2e 0a 2a 2a 0a  he unix VFS..**.
377b0 2a 2a 20 43 68 61 6e 67 69 6e 67 20 74 68 65 20  ** Changing the 
377c0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 76 61  value of this va
377d0 72 69 61 62 6c 65 20 77 68 69 6c 65 20 61 20 64  riable while a d
377e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
377f0 6f 6e 20 69 73 0a 2a 2a 20 6f 70 65 6e 20 63 61  on is.** open ca
37800 6e 20 72 65 73 75 6c 74 20 69 6e 20 61 20 63 6f  n result in a co
37810 72 72 75 70 74 20 64 61 74 61 62 61 73 65 2e 0a  rrupt database..
37820 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  **.** It is not 
37830 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
37840 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
37850 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61  able in more tha
37860 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20  n one.** thread 
37870 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69  at a time.  It i
37880 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65  s not safe to re
37890 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ad or modify thi
378a0 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66  s variable.** if
378b0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
378c0 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
378d0 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61  g used at the sa
378e0 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70  me time in a sep
378f0 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e  arate.** thread.
37900 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64  .** It is intend
37910 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ed that this var
37920 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63  iable be set onc
37930 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  e.** as part of 
37940 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
37950 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72  zation and befor
37960 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
37970 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e  erface.** routin
37980 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  es have been cal
37990 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69  led and that thi
379a0 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69  s variable remai
379b0 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74  n unchanged.** t
379c0 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a  hereafter..**.**
379d0 20 5e 54 68 65 20 5b 64 61 74 61 5f 73 74 6f 72   ^The [data_stor
379e0 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
379f0 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74  ma] may modify t
37a00 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64  his variable and
37a10 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20   cause.** it to 
37a20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
37a30 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
37a40 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20  qlite3_malloc]. 
37a50 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a   ^Furthermore,.*
37a60 2a 20 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72  * the [data_stor
37a70 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
37a80 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d  ma] always assum
37a90 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69  es that any stri
37aa0 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20  ng.** that this 
37ab0 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20  variable points 
37ac0 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65  to is held in me
37ad0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
37ae0 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
37af0 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20  malloc] and the 
37b00 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d  pragma may attem
37b10 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20  pt to free that 
37b20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20  memory.** using 
37b30 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a  [sqlite3_free]..
37b40 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69  ** Hence, if thi
37b50 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f  s variable is mo
37b60 64 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c  dified directly,
37b70 20 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c   either it shoul
37b80 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c  d be.** made NUL
37b90 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69  L or made to poi
37ba0 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74  nt to memory obt
37bb0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
37bc0 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f  te3_malloc].** o
37bd0 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f  r else the use o
37be0 66 20 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72  f the [data_stor
37bf0 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
37c00 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76  ma] should be av
37c10 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  oided..*/.SQLITE
37c20 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71  _EXTERN char *sq
37c30 6c 69 74 65 33 5f 64 61 74 61 5f 64 69 72 65 63  lite3_data_direc
37c40 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tory;../*.** CAP
37c50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20  I3REF: Test For 
37c60 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65  Auto-Commit Mode
37c70 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
37c80 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a  utocommit mode}.
37c90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
37ca0 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
37cb0 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  t() interface re
37cc0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f  turns non-zero o
37cd0 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65  r.** zero if the
37ce0 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20   given database 
37cf0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72  connection is or
37d00 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63   is not in autoc
37d10 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72  ommit mode,.** r
37d20 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41  espectively.  ^A
37d30 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
37d40 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  s on by default.
37d50 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20  .** ^Autocommit 
37d60 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64  mode is disabled
37d70 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74   by a [BEGIN] st
37d80 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74  atement..** ^Aut
37d90 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
37da0 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20  re-enabled by a 
37db0 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c  [COMMIT] or [ROL
37dc0 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  LBACK]..**.** If
37dd0 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f   certain kinds o
37de0 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f  f errors occur o
37df0 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69  n a statement wi
37e00 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61  thin a multi-sta
37e10 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61  tement.** transa
37e20 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e  ction (errors in
37e30 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f  cluding [SQLITE_
37e40 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49  FULL], [SQLITE_I
37e50 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  OERR],.** [SQLIT
37e60 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54  E_NOMEM], [SQLIT
37e70 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51  E_BUSY], and [SQ
37e80 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29  LITE_INTERRUPT])
37e90 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61   then the.** tra
37ea0 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62  nsaction might b
37eb0 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
37ec0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68  tomatically.  Th
37ed0 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a  e only way to.**
37ee0 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65   find out whethe
37ef0 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74  r SQLite automat
37f00 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
37f10 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
37f20 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65  on after.** an e
37f30 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74  rror is to use t
37f40 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  his function..**
37f50 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74  .** If another t
37f60 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68  hread changes th
37f70 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61  e autocommit sta
37f80 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62  tus of the datab
37f90 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
37fa0 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75  n while this rou
37fb0 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c  tine is running,
37fc0 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
37fd0 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64   value.** is und
37fe0 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  efined..*/.int s
37ff0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
38000 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b  ommit(sqlite3*);
38010 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38020 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62  : Find The Datab
38030 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20  ase Handle Of A 
38040 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
38050 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  nt.**.** ^The sq
38060 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
38070 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
38080 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
38090 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
380a0 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61  le.** to which a
380b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
380c0 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20  ment] belongs.  
380d0 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63  ^The [database c
380e0 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65  onnection].** re
380f0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
38100 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74  3_db_handle is t
38110 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
38120 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
38130 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66 69   that was the fi
38140 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rst argument.** 
38150 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
38160 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61  prepare_v2()] ca
38170 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69 61  ll (or its varia
38180 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75 73  nts) that was us
38190 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20  ed to.** create 
381a0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  the statement in
381b0 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65   the first place
381c0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
381d0 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28  lite3_db_handle(
381e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
381f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
38200 20 52 65 74 75 72 6e 20 54 68 65 20 46 69 6c 65   Return The File
38210 6e 61 6d 65 20 46 6f 72 20 41 20 44 61 74 61 62  name For A Datab
38220 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
38230 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
38240 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 44 2c  3_db_filename(D,
38250 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  N) interface ret
38260 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
38270 6f 20 61 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  o a filename.** 
38280 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
38290 64 61 74 61 62 61 73 65 20 4e 20 6f 66 20 63 6f  database N of co
382a0 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 5e 54 68  nnection D.  ^Th
382b0 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
382c0 66 69 6c 65 0a 2a 2a 20 68 61 73 20 74 68 65 20  file.** has the 
382d0 6e 61 6d 65 20 22 6d 61 69 6e 22 2e 20 20 49 66  name "main".  If
382e0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 61 74 74   there is no att
382f0 61 63 68 65 64 20 64 61 74 61 62 61 73 65 20 4e  ached database N
38300 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
38310 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  .** connection D
38320 2c 20 6f 72 20 69 66 20 64 61 74 61 62 61 73 65  , or if database
38330 20 4e 20 69 73 20 61 20 74 65 6d 70 6f 72 61 72   N is a temporar
38340 79 20 6f 72 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  y or in-memory d
38350 61 74 61 62 61 73 65 2c 20 74 68 65 6e 0a 2a 2a  atabase, then.**
38360 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
38370 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
38380 2a 2a 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  ** ^The filename
38390 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
383a0 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  s function is th
383b0 65 20 6f 75 74 70 75 74 20 6f 66 20 74 68 65 0a  e output of the.
383c0 2a 2a 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  ** xFullPathname
383d0 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
383e0 56 46 53 5d 2e 20 20 5e 49 6e 20 6f 74 68 65 72  VFS].  ^In other
383f0 20 77 6f 72 64 73 2c 20 74 68 65 20 66 69 6c 65   words, the file
38400 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  name.** will be 
38410 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
38420 6e 61 6d 65 2c 20 65 76 65 6e 20 69 66 20 74 68  name, even if th
38430 65 20 66 69 6c 65 6e 61 6d 65 20 75 73 65 64 0a  e filename used.
38440 2a 2a 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  ** to open the d
38450 61 74 61 62 61 73 65 20 6f 72 69 67 69 6e 61 6c  atabase original
38460 6c 79 20 77 61 73 20 61 20 55 52 49 20 6f 72 20  ly was a URI or 
38470 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d  relative pathnam
38480 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  e..*/.const char
38490 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c   *sqlite3_db_fil
384a0 65 6e 61 6d 65 28 73 71 6c 69 74 65 33 20 2a 64  ename(sqlite3 *d
384b0 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  b, const char *z
384c0 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  DbName);../*.** 
384d0 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
384e0 69 6e 65 20 69 66 20 61 20 64 61 74 61 62 61 73  ine if a databas
384f0 65 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79 0a 2a  e is read-only.*
38500 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
38510 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28 44 2c  3_db_readonly(D,
38520 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  N) interface ret
38530 75 72 6e 73 20 31 20 69 66 20 74 68 65 20 64 61  urns 1 if the da
38540 74 61 62 61 73 65 20 4e 0a 2a 2a 20 6f 66 20 63  tabase N.** of c
38550 6f 6e 6e 65 63 74 69 6f 6e 20 44 20 69 73 20 72  onnection D is r
38560 65 61 64 2d 6f 6e 6c 79 2c 20 30 20 69 66 20 69  ead-only, 0 if i
38570 74 20 69 73 20 72 65 61 64 2f 77 72 69 74 65 2c  t is read/write,
38580 20 6f 72 20 2d 31 20 69 66 20 4e 20 69 73 20 6e   or -1 if N is n
38590 6f 74 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  ot.** the name o
385a0 66 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20  f a database on 
385b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2f  connection D..*/
385c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f  .int sqlite3_db_
385d0 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33  readonly(sqlite3
385e0 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 61 72   *db, const char
385f0 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a   *zDbName);../*.
38600 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e  ** CAPI3REF: Fin
38610 64 20 74 68 65 20 6e 65 78 74 20 70 72 65 70 61  d the next prepa
38620 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
38630 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
38640 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
38650 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78  inter to the nex
38660 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  t [prepared stat
38670 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20  ement] after.** 
38680 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64  pStmt associated
38690 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
386a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
386b0 70 44 62 2e 20 20 5e 49 66 20 70 53 74 6d 74 20  pDb.  ^If pStmt 
386c0 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20  is NULL.** then 
386d0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72  this interface r
386e0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
386f0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 70 72   to the first pr
38700 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
38710 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
38720 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65  ith the database
38730 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e   connection pDb.
38740 20 20 5e 49 66 20 6e 6f 20 70 72 65 70 61 72 65    ^If no prepare
38750 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73  d statement.** s
38760 61 74 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e  atisfies the con
38770 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20  ditions of this 
38780 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75  routine, it retu
38790 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20  rns NULL..**.** 
387a0 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  The [database co
387b0 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65  nnection] pointe
387c0 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f  r D in a call to
387d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  .** [sqlite3_nex
387e0 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73  t_stmt(D,S)] mus
387f0 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70  t refer to an op
38800 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  en database.** c
38810 6f 6e 6e 65 63 74 69 6f 6e