/ Hex Artifact Content
Login

Artifact 31045976254225e6bf046a96e87b40fa4c1d55e4:


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 28 29 20 69  qlite3_close() i
2f20: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64  s called on a [d
2f30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2f40: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68  on] that still h
2f50: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e  as.** outstandin
2f60: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  g [prepared stat
2f70: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
2f80: 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a  andles], and/or.
2f90: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
2fa0: 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e  up] objects then
2fb0: 20 69 74 20 72 65 74 75 72 6e 73 20 53 51 4c 49   it returns SQLI
2fc0: 54 45 5f 4f 4b 20 62 75 74 20 74 68 65 20 64 65  TE_OK but the de
2fd0: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
2fe0: 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 65   resources is de
2ff0: 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c  ferred until all
3000: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3010: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
3020: 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b  ndles],.** and [
3030: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20  sqlite3_backup] 
3040: 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f  objects are also
3050: 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a   destroyed..**.*
3060: 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65  * ^If an [sqlite
3070: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73  3] object is des
3080: 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74  troyed while a t
3090: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70  ransaction is op
30a0: 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73  en,.** the trans
30b0: 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61  action is automa
30c0: 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
30d0: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  ack..**.** The C
30e0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
30f0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d  qlite3_close(C)]
3100: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c   and [sqlite3_cl
3110: 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75  ose_v2(C)].** mu
3120: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
3130: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
3140: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
3150: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
3160: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
3170: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
3180: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
3190: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
31a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
31b0: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
31c0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
31d0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
31e0: 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65  lose() or sqlite
31f0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74  3_close_v2() wit
3200: 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
3210: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
3220: 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
3230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
3240: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 29  _close(sqlite3*)
3250: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  ;.int sqlite3_cl
3260: 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a 29  ose_v2(sqlite3*)
3270: 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70  ;../*.** The typ
3280: 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b  e for a callback
3290: 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
32a0: 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64  is is legacy and
32b0: 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74   deprecated.  It
32c0: 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72   is included for
32d0: 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63   historical.** c
32e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64  ompatibility and
32f0: 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74   is not document
3300: 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69  ed..*/.typedef i
3310: 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c  nt (*sqlite3_cal
3320: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74  lback)(void*,int
3330: 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29  ,char**, char**)
3340: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
3350: 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72  F: One-Step Quer
3360: 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65  y Execution Inte
3370: 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rface.**.** The 
3380: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3390: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
33a0: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
33b0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
33c0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
33d0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
33e0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
33f0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
3400: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
3410: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
3420: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
3430: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
3440: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
3450: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
3460: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
3470: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
3480: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
3490: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
34a0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
34b0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
34c0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
34d0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
34e0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
34f0: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
3500: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
3510: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3520: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
3530: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
3540: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
3550: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
3560: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
3570: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3580: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
3590: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
35a0: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
35b0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
35c0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
35d0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
35e0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
35f0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3600: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3610: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
3620: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
3630: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
3640: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
3650: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
3660: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
3670: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3680: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
3690: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
36a0: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
36b0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
36c0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
36d0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
36e0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
36f0: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
3700: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3710: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3720: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
3730: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
3740: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
3750: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
3760: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
3770: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
3780: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
3790: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
37a0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
37b0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
37c0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
37d0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
37e0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
37f0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
3800: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
3810: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
3820: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
3830: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
3840: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
3850: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
3860: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
3870: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
3880: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
3890: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
38a0: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
38b0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
38c0: 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71  eter of.** of sq
38d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74  lite3_exec() aft
38e0: 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
38f0: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e  sage string is n
3900: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
3910: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20  .** ^If the 5th 
3920: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3930: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
3940: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65  ot NULL and no e
3950: 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20  rrors.** occur, 
3960: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  then sqlite3_exe
3970: 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69  c() sets the poi
3980: 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20  nter in its 5th 
3990: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
39a0: 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75  NULL before retu
39b0: 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rning..**.** ^If
39c0: 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63   an sqlite3_exec
39d0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  () callback retu
39e0: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
39f0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3a00: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
3a10: 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  rns SQLITE_ABORT
3a20: 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e   without invokin
3a30: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  g the callback a
3a40: 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68  gain and.** with
3a50: 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20  out running any 
3a60: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73  subsequent SQL s
3a70: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
3a80: 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65   ^The 2nd argume
3a90: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3aa0: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3ab0: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  k function is th
3ac0: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
3ad0: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
3ae0: 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20  sult.  ^The 3rd 
3af0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
3b00: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3b10: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  * callback is an
3b20: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3b30: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62  rs to strings ob
3b40: 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f  tained as if fro
3b50: 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  m.** [sqlite3_co
3b60: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e  lumn_text()], on
3b70: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d  e for each colum
3b80: 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65  n.  ^If an eleme
3b90: 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c  nt of a.** resul
3ba0: 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68  t row is NULL th
3bb0: 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
3bc0: 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e  ding string poin
3bd0: 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73  ter for the.** s
3be0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3bf0: 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c  llback is a NULL
3c00: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
3c10: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  4th argument to 
3c20: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3c30: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3c40: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
3c50: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
3c60: 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20  s where each.** 
3c70: 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73  entry represents
3c80: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72   the name of cor
3c90: 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c  responding resul
3ca0: 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61  t column as obta
3cb0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
3cc0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
3cd0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  e()]..**.** ^If 
3ce0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
3cf0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3d00: 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  c() is a NULL po
3d10: 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72  inter, a pointer
3d20: 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  .** to an empty 
3d30: 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69  string, or a poi
3d40: 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69  nter that contai
3d50: 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61  ns only whitespa
3d60: 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51  ce and/or .** SQ
3d70: 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e  L comments, then
3d80: 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   no SQL statemen
3d90: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
3da0: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
3db0: 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  e.** is not chan
3dc0: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72  ged..**.** Restr
3dd0: 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ictions:.**.** <
3de0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
3df0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3e00: 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   insure that the
3e10: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3e20: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3e30: 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61  .**      is a va
3e40: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61  lid and open [da
3e50: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3e60: 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  n]..** <li> The 
3e70: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3e80: 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61   not close [data
3e90: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
3ea0: 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a   specified by.**
3eb0: 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61        the 1st pa
3ec0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
3ed0: 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20  e3_exec() while 
3ee0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3ef0: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c  s running..** <l
3f00: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
3f10: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69  on must not modi
3f20: 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  fy the SQL state
3f30: 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64  ment text passed
3f40: 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68   into.**      th
3f50: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
3f60: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
3f70: 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  ) while sqlite3_
3f80: 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e  exec() is runnin
3f90: 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69  g..** </ul>.*/.i
3fa0: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
3fb0: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  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 2f 2a                /*
3fe0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
3ff0: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
4000: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
4030: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e  valuated */.  in
4040: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
4050: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
4060: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
4070: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
4080: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 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 2f 2a                /*
40b0: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
40c0: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
40d0: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **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 2f 2a 20 45 72 72            /* Err
4100: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
4110: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
4120: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
4130: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
4140: 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b  RDS: SQLITE_OK {
4150: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72  error code} {err
4160: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59  or codes}.** KEY
4170: 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63  WORDS: {result c
4180: 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64  ode} {result cod
4190: 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  es}.**.** Many S
41a0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
41b0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
41c0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
41d0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
41e0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
41f0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4200: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4210: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4220: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4230: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4240: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4250: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4260: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
4270: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
4280: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a   result codes],.
4290: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  ** [sqlite3_vtab
42a0: 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
42b0: 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b  [SQLITE_ROLLBACK
42c0: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
42d0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
42e0: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
42f0: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
4300: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
4310: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
4320: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
4330: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
4340: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
4350: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
4360: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
4370: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4380: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
4390: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
43a0: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
43b0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
43c0: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
43d0: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
43e0: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
43f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4400: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
4410: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
4420: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
4430: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
4440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
4450: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
4460: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
4470: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
4480: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4490: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
44a0: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
44b0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
44c0: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
44d0: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
44e0: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
44f0: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
4500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4510: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
4520: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
4530: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
4540: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4550: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
4560: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
4570: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
4580: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4590: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
45a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
45b0: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
45c0: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
45d0: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
45e0: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
45f0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
4600: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
4610: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
4620: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
4630: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4640: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
4650: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
4660: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
4670: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
4680: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4690: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
46a0: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
46b0: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
46c0: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
46d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
46e0: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
46f0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
4700: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
4710: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4720: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
4730: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
4740: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
4750: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
4760: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
4770: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
4780: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4790: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
47a0: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
47b0: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
47c0: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
47d0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
47e0: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
47f0: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
4800: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
4810: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
4820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
4830: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
4840: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
4850: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
4860: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
4870: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
4880: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4890: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
48a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
48b0: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
48c0: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
48d0: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
48e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
48f0: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
4900: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
4910: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
4920: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
4930: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
4940: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
4950: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
4960: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4970: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
4980: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4990: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
49a0: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
49b0: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
49c0: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
49d0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
49e0: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
49f0: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
4a00: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
4a10: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
4a20: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
4a30: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
4a40: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4a50: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4a60: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4a70: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4a80: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4a90: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4aa0: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4ab0: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4ac0: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4ad0: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4ae0: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4af0: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4b00: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4b10: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4b20: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4b30: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
4b40: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4b50: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4b60: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4b70: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4b80: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4b90: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4ba0: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4bb0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4bc0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4bd0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4be0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
4bf0: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
4c00: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
4c10: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
4c20: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
4c30: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
4c40: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4c50: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4c60: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4c70: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4c80: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4c90: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4ca0: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4cb0: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4cc0: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4cd0: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4ce0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4cf0: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
4d00: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
4d10: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
4d20: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
4d30: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
4d40: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4d50: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4d60: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4d70: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4d80: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4d90: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4da0: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4db0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4dc0: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4dd0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4de0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
4df0: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
4e00: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
4e10: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
4e20: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4e30: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
4e40: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4e50: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
4e60: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
4e70: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20  t codes will be 
4e80: 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74  expand.** over t
4e90: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ime.  Software t
4ea0: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65  hat uses extende
4eb0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73  d result codes s
4ec0: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20  hould expect.** 
4ed0: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c  to see new resul
4ee0: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72  t codes in futur
4ef0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
4f00: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
4f10: 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74  SQLITE_OK result
4f20: 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72   code will never
4f30: 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49   be extended.  I
4f40: 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a  t will always.**
4f50: 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f   be exactly zero
4f60: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4f70: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
4f80: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4f90: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
4fa0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4fb0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
4fc0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
4fd0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
4fe0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4ff0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5000: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5010: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
5020: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5030: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5040: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5050: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5060: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5070: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5080: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5090: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
50a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
50b0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
50c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
50d0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
50e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
50f0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5100: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5110: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
5120: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5130: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5140: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5150: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5170: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5180: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5190: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
51a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51b0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
51c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
51d0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
51e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51f0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5200: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5210: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
5220: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5230: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5240: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5250: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5260: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5270: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5280: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5290: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
52a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52b0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
52c0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
52d0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
52e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52f0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5300: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5310: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
5320: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5330: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5340: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5350: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5360: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5370: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5380: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5390: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
53a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53b0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
53c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53d0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
53e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53f0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5400: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5410: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5470: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5490: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54b0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54d0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54f0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5500: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5510: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
5520: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5530: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5540: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5550: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5560: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5570: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5580: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5590: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
55a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
55b0: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
55c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
55d0: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
55e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
55f0: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
5600: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5610: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
5620: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5630: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
5640: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
5650: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
5660: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5670: 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20  TE_CORRUPT_VTAB 
5680: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5690: 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c  TE_CORRUPT | (1<
56a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56b0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43  ITE_READONLY_REC
56c0: 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c  OVERY       (SQL
56d0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
56e0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
56f0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43  QLITE_READONLY_C
5700: 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53  ANTLOCK       (S
5710: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
5720: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5730: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
5740: 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20  _ROLLBACK       
5750: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
5760: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
5770: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f  ne SQLITE_ABORT_
5780: 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20  ROLLBACK        
5790: 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20    (SQLITE_ABORT 
57a0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
57b0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
57c0: 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20  INT_CHECK       
57d0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
57e0: 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  INT | (1<<8)).#d
57f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5800: 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f  STRAINT_COMMITHO
5810: 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  OK   (SQLITE_CON
5820: 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29  STRAINT | (2<<8)
5830: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5840: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45  _CONSTRAINT_FORE
5850: 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45  IGNKEY   (SQLITE
5860: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33  _CONSTRAINT | (3
5870: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5880: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5890: 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51  FUNCTION     (SQ
58a0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
58b0: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
58c0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
58d0: 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20  INT_NOTNULL     
58e0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
58f0: 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64  INT | (5<<8)).#d
5900: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5910: 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b  STRAINT_PRIMARYK
5920: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
5930: 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29  STRAINT | (6<<8)
5940: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5950: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47  _CONSTRAINT_TRIG
5960: 47 45 52 20 20 20 20 20 20 28 53 51 4c 49 54 45  GER      (SQLITE
5970: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37  _CONSTRAINT | (7
5980: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5990: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
59a0: 55 4e 49 51 55 45 20 20 20 20 20 20 20 28 53 51  UNIQUE       (SQ
59b0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
59c0: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
59d0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
59e0: 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20 20  INT_VTAB        
59f0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5a00: 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 0a 2f  INT | (9<<8))../
5a10: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
5a20: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
5a30: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  en Operations.**
5a40: 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61  .** These bit va
5a50: 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lues are intende
5a60: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65  d for use in the
5a70: 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65  .** 3rd paramete
5a80: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
5a90: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
5aa0: 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e  erface and.** in
5ab0: 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
5ac0: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
5ad0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
5ae0: 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  thod..*/.#define
5af0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
5b00: 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78  DONLY         0x
5b10: 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20  00000001  /* Ok 
5b20: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5b30: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5b40: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
5b50: 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78  DWRITE        0x
5b60: 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20  00000002  /* Ok 
5b70: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5b80: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5b90: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
5ba0: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78  ATE           0x
5bb0: 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20  00000004  /* Ok 
5bc0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5bd0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5be0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c   SQLITE_OPEN_DEL
5bf0: 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78  ETEONCLOSE    0x
5c00: 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53  00000008  /* VFS
5c10: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5c20: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
5c30: 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78  LUSIVE        0x
5c40: 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53  00000010  /* VFS
5c50: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5c60: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54   SQLITE_OPEN_AUT
5c70: 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78  OPROXY        0x
5c80: 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53  00000020  /* VFS
5c90: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5ca0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
5cb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5cc0: 30 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20  00000040  /* Ok 
5cd0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5ce0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5cf0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d   SQLITE_OPEN_MEM
5d00: 4f 52 59 20 20 20 20 20 20 20 20 20 20 20 30 78  ORY           0x
5d10: 30 30 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20  00000080  /* Ok 
5d20: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5d30: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5d40: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
5d50: 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  N_DB          0x
5d60: 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53  00000100  /* VFS
5d70: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5d80: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
5d90: 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  P_DB          0x
5da0: 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53  00000200  /* VFS
5db0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5dc0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41   SQLITE_OPEN_TRA
5dd0: 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78  NSIENT_DB     0x
5de0: 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53  00000400  /* VFS
5df0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5e00: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
5e10: 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  N_JOURNAL     0x
5e20: 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53  00000800  /* VFS
5e30: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5e40: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
5e50: 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  P_JOURNAL     0x
5e60: 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53  00001000  /* VFS
5e70: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5e80: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42   SQLITE_OPEN_SUB
5e90: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78  JOURNAL       0x
5ea0: 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53  00002000  /* VFS
5eb0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5ec0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53   SQLITE_OPEN_MAS
5ed0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78  TER_JOURNAL   0x
5ee0: 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53  00004000  /* VFS
5ef0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5f00: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d   SQLITE_OPEN_NOM
5f10: 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78  UTEX          0x
5f20: 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20  00008000  /* Ok 
5f30: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5f40: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5f50: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c   SQLITE_OPEN_FUL
5f60: 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78  LMUTEX        0x
5f70: 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00010000  /* Ok 
5f80: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5f90: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5fa0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
5fb0: 52 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78  REDCACHE      0x
5fc0: 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00020000  /* Ok 
5fd0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5fe0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5ff0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
6000: 56 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78  VATECACHE     0x
6010: 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00040000  /* Ok 
6020: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
6030: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
6040: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c   SQLITE_OPEN_WAL
6050: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6060: 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53  00080000  /* VFS
6070: 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73   only */../* Res
6080: 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20  erved:          
6090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
60a0: 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a  x00F00000 */../*
60b0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
60c0: 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73  vice Characteris
60d0: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  tics.**.** The x
60e0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
60f0: 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20  stics method of 
6100: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
6110: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65  methods].** obje
6120: 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ct returns an in
6130: 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61  teger which is a
6140: 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65   vector of these
6150: 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65  .** bit values e
6160: 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68  xpressing I/O ch
6170: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66  aracteristics of
6180: 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67   the mass storag
6190: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
61a0: 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20   holds the file 
61b0: 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
61c0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
61d0: 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a   refers to..**.*
61e0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
61f0: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  AP_ATOMIC proper
6200: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
6210: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
6220: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
6230: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
6240: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
6250: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
6260: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
6270: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
6280: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
6290: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
62a0: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
62b0: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
62c0: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
62d0: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
62e0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
62f0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
6300: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
6310: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
6320: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
6330: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
6340: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
6350: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
6360: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
6370: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
6380: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
6390: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
63a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
63b0: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
63c0: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
63d0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
63e0: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
63f0: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
6400: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
6410: 57 72 69 74 65 28 29 2e 20 20 54 68 65 20 53 51  Write().  The SQ
6420: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
6430: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70  SAFE_OVERWRITE p
6440: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
6450: 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f  at.** after rebo
6460: 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ot following a c
6470: 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f  rash or power lo
6480: 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74  ss, the only byt
6490: 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20  es in a.** file 
64a0: 74 68 61 74 20 77 65 72 65 20 77 72 69 74 74 65  that were writte
64b0: 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69 63 61  n at the applica
64c0: 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74  tion level might
64d0: 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a   have changed.**
64e0: 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65   and that adjace
64f0: 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62  nt bytes, even b
6500: 79 74 65 73 20 77 69 74 68 69 6e 20 74 68 65 20  ytes within the 
6510: 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a  same sector are.
6520: 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ** guaranteed to
6530: 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   be unchanged..*
6540: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6550: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20  _IOCAP_ATOMIC   
6560: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6570: 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65  00000001.#define
6580: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6590: 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 20  OMIC512         
65a0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a       0x00000002.
65b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
65c0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20  OCAP_ATOMIC1K   
65d0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
65e0: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
65f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6600: 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC2K            
6610: 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64     0x00000008.#d
6620: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6630: 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20  AP_ATOMIC4K     
6640: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6650: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
6660: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6670: 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  8K              
6680: 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66   0x00000020.#def
6690: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
66a0: 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20  _ATOMIC16K      
66b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
66c0: 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  40.#define SQLIT
66d0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
66e0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
66f0: 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e  x00000080.#defin
6700: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6710: 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20  TOMIC64K        
6720: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
6730: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6740: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
6750: 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30  D            0x0
6760: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20  0000200.#define 
6770: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
6780: 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20  UENTIAL         
6790: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23      0x00000400.#
67a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
67b0: 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f  CAP_UNDELETABLE_
67c0: 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30  WHEN_OPEN  0x000
67d0: 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00800.#define SQ
67e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
67f0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
6800: 20 20 30 78 30 30 30 30 31 30 30 30 0a 0a 2f 2a    0x00001000../*
6810: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
6820: 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c  le Locking Level
6830: 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  s.**.** SQLite u
6840: 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ses one of these
6850: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6860: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
6870: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
6880: 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74  ls it makes to t
6890: 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  he xLock() and x
68a0: 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73  Unlock() methods
68b0: 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  .** of an [sqlit
68c0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
68d0: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e  bject..*/.#defin
68e0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f  e SQLITE_LOCK_NO
68f0: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64  NE          0.#d
6900: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6910: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20  K_SHARED        
6920: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6930: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20  _LOCK_RESERVED  
6940: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
6950: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6960: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  G       3.#defin
6970: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58  e SQLITE_LOCK_EX
6980: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f  CLUSIVE     4../
6990: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
69a0: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54  ynchronization T
69b0: 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ype Flags.**.** 
69c0: 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f  When SQLite invo
69d0: 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20  kes the xSync() 
69e0: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20  method of an.** 
69f0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6a00: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75  ods] object it u
6a10: 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f  ses a combinatio
6a20: 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e  n of.** these in
6a30: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
6a40: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
6a50: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ent..**.** When 
6a60: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
6a70: 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73  DATAONLY flag is
6a80: 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20   used, it means 
6a90: 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63  that the.** sync
6aa0: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20   operation only 
6ab0: 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64  needs to flush d
6ac0: 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72  ata to mass stor
6ad0: 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69  age.  Inode.** i
6ae0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20  nformation need 
6af0: 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20  not be flushed. 
6b00: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
6b10: 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c  r bits of the fl
6b20: 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49  ag.** equal SQLI
6b30: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20  TE_SYNC_NORMAL, 
6b40: 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73  that means to us
6b50: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6b60: 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49   semantics..** I
6b70: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
6b80: 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49   bits equal SQLI
6b90: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68  TE_SYNC_FULL, th
6ba0: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75  at means.** to u
6bb0: 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c  se Mac OS X styl
6bc0: 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65  e fullsync inste
6bd0: 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a  ad of fsync()..*
6be0: 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66  *.** Do not conf
6bf0: 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53  use the SQLITE_S
6c00: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
6c10: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6c20: 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68  flags.** with th
6c30: 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  e [PRAGMA synchr
6c40: 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e  onous]=NORMAL an
6c50: 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  d [PRAGMA synchr
6c60: 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73  onous]=FULL.** s
6c70: 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73  ettings.  The [s
6c80: 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d  ynchronous pragm
6c90: 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68  a] determines wh
6ca0: 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a  en calls to the.
6cb0: 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74  ** xSync VFS met
6cc0: 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70  hod occur and ap
6cd0: 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20  plies uniformly 
6ce0: 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66  across all platf
6cf0: 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  orms..** The SQL
6d00: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
6d10: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
6d20: 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72  FULL flags deter
6d30: 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72  mine how.** ener
6d40: 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75  getic or rigorou
6d50: 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68  s or forceful th
6d60: 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  e sync operation
6d70: 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c  s are and.** onl
6d80: 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65  y make a differe
6d90: 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66  nce on Mac OSX f
6da0: 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53  or the default S
6db0: 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28  QLite code..** (
6dc0: 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20  Third-party VFS 
6dd0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
6de0: 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20  might also make 
6df0: 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a  the distinction.
6e00: 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54  ** between SQLIT
6e10: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
6e20: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
6e30: 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68  LL, but among th
6e40: 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73  e.** operating s
6e50: 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20  ystems natively 
6e60: 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
6e70: 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53  ite, only Mac OS
6e80: 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74  X.** cares about
6e90: 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e   the difference.
6ea0: 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ).*/.#define SQL
6eb0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
6ec0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23         0x00002.#
6ed0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
6ee0: 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20  NC_FULL         
6ef0: 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65   0x00003.#define
6f00: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
6f10: 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30  AONLY      0x000
6f20: 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
6f30: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
6f40: 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c   Open File Handl
6f50: 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69  e.**.** An [sqli
6f60: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
6f70: 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f   represents an o
6f80: 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20  pen file in the 
6f90: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
6fa0: 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20   | OS interface 
6fb0: 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64  layer].  Individ
6fc0: 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ual OS interface
6fd0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
6fe0: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74  ons will.** want
6ff0: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69   to subclass thi
7000: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65  s object by appe
7010: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c  nding additional
7020: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74   fields.** for t
7030: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54  heir own use.  T
7040: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72  he pMethods entr
7050: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  y is a pointer t
7060: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
7070: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
7080: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
7090: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72   methods for per
70a0: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f  forming.** I/O o
70b0: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
70c0: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74   open file..*/.t
70d0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
70e0: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74  lite3_file sqlit
70f0: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20  e3_file;.struct 
7100: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20  sqlite3_file {. 
7110: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
7120: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7130: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20   *pMethods;  /* 
7140: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f  Methods for an o
7150: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a  pen file */.};..
7160: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7170: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c  OS Interface Fil
7180: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64  e Virtual Method
7190: 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45  s Object.**.** E
71a0: 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64  very file opened
71b0: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
71c0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
71d0: 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a  od populates an.
71e0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
71f0: 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f  ] object (or, mo
7200: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73  re commonly, a s
7210: 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a  ubclass of the.*
7220: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
7230: 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20   object) with a 
7240: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
7250: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
7260: 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  bject..** This o
7270: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
7280: 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74  e methods used t
7290: 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
72a0: 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  s operations.** 
72b0: 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e  against the open
72c0: 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65   file represente
72d0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
72e0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a  3_file] object..
72f0: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71  **.** If the [sq
7300: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7310: 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65   method sets the
7320: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
7330: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a  ethods element .
7340: 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ** to a non-NULL
7350: 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74   pointer, then t
7360: 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  he sqlite3_io_me
7370: 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74  thods.xClose met
7380: 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e  hod.** may be in
7390: 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68  voked even if th
73a0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
73b0: 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74  Open] reported t
73c0: 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20  hat it failed.  
73d0: 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20  The.** only way 
73e0: 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c  to prevent a cal
73f0: 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c  l to xClose foll
7400: 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b  owing a failed [
7410: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7420: 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65  n].** is for the
7430: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7440: 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20  pen] to set the 
7450: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
7460: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a  thods element.**
7470: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
7480: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
7490: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
74a0: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
74b0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
74c0: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
74d0: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
74e0: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
74f0: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
7500: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
7510: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
7520: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
7530: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
7540: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
7550: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
7560: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
7570: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
7580: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
7590: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
75a0: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
75b0: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
75c0: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
75d0: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
75e0: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
75f0: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
7600: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7610: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
7620: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7630: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
7640: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7650: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
7660: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7670: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
7680: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7690: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
76a0: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
76b0: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
76c0: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
76d0: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
76e0: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
76f0: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
7700: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
7710: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
7720: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
7730: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
7740: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
7750: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
7760: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
7770: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
7780: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
7790: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
77a0: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
77b0: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
77c0: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
77d0: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
77e0: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
77f0: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
7800: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
7810: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
7820: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
7830: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7840: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
7850: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
7860: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
7870: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7880: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
7890: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
78a0: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
78b0: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
78c0: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
78d0: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
78e0: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
78f0: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
7900: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
7910: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
7920: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
7930: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
7940: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
7950: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
7960: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
7970: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
7980: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
7990: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
79a0: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
79b0: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
79c0: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
79d0: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
79e0: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
79f0: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
7a00: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
7a10: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
7a20: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
7a30: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
7a40: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
7a50: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
7a60: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
7a70: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
7a80: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
7a90: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
7aa0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
7ab0: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
7ac0: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
7ad0: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
7ae0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
7af0: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
7b00: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
7b10: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
7b20: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
7b30: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
7b40: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
7b50: 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  .  VFS implement
7b60: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a  ations should.**
7b70: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
7b80: 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69  NOTFOUND] for fi
7b90: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64  le control opcod
7ba0: 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  es that they do 
7bb0: 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65  not.** recognize
7bc0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
7bd0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
7be0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
7bf0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
7c00: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
7c10: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
7c20: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
7c30: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
7c40: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
7c50: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
7c60: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
7c70: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
7c80: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
7c90: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
7ca0: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
7cb0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
7cc0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
7cd0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
7ce0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
7cf0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
7d00: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
7d10: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7d20: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
7d30: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7d40: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
7d50: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7d60: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
7d70: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7d80: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
7d90: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7da0: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
7db0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7dc0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
7dd0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7de0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
7df0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7e00: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
7e10: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7e20: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
7e30: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7e40: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
7e50: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7e60: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
7e70: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
7e80: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
7e90: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
7ea0: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
7eb0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
7ec0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
7ed0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
7ee0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
7ef0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
7f00: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
7f10: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
7f20: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
7f30: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
7f40: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
7f50: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
7f60: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
7f70: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
7f80: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
7f90: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
7fa0: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
7fb0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
7fc0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
7fd0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
7fe0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
7ff0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
8000: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
8010: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
8020: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
8030: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
8040: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
8050: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
8060: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
8070: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
8080: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
8090: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
80a0: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
80b0: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
80c0: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
80d0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
80e0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
80f0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
8100: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
8110: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
8120: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
8130: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
8140: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
8150: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
8160: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
8170: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
8180: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
8190: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
81a0: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
81b0: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
81c0: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
81d0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
81e0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
81f0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
8200: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
8210: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8220: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
8230: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
8240: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
8250: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
8260: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
8270: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
8280: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
8290: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
82a0: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
82b0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
82c0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
82d0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
82e0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
82f0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
8300: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
8310: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
8320: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
8330: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
8340: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
8350: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
8360: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8370: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
8380: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
8390: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
83a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
83b0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
83c0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
83d0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
83e0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
83f0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
8400: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
8410: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
8420: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
8430: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
8440: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
8450: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8460: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
8470: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
8480: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8490: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
84a0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
84b0: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
84c0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29    int (*xShmMap)
84d0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
84e0: 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73  int iPg, int pgs
84f0: 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c  z, int, void vol
8500: 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20  atile**);.  int 
8510: 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69  (*xShmLock)(sqli
8520: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
8530: 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e  ffset, int n, in
8540: 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64  t flags);.  void
8550: 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28   (*xShmBarrier)(
8560: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8570: 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61    int (*xShmUnma
8580: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
8590: 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67  , int deleteFlag
85a0: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
85b0: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
85c0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f  for version 2 */
85d0: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
85e0: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
85f0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
8600: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
8610: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
8620: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
8630: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a  ntrol Opcodes.**
8640: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
8650: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  r constants are 
8660: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20  opcodes for the 
8670: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
8680: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  hod.** of the [s
8690: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
86a0: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f  s] object and fo
86b0: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  r the [sqlite3_f
86c0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a  ile_control()].*
86d0: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  * interface..**.
86e0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
86f0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
8700: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
8710: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
8720: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
8730: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
8740: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
8750: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
8760: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
8770: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
8780: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
8790: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
87a0: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
87b0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
87c0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
87d0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
87e0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
87f0: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
8800: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
8810: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
8820: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
8830: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
8840: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
8850: 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e  sting and only n
8860: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
8870: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
8880: 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69  _TEST.** is defi
8890: 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  ned..** <ul>.** 
88a0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
88b0: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a  TL_SIZE_HINT]].*
88c0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
88d0: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f  NTL_SIZE_HINT] o
88e0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79  pcode is used by
88f0: 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20   SQLite to give 
8900: 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72  the VFS.** layer
8910: 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c   a hint of how l
8920: 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73  arge the databas
8930: 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77  e file will grow
8940: 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68   to be during th
8950: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61  e.** current tra
8960: 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20  nsaction.  This 
8970: 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72  hint is not guar
8980: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63  anteed to be acc
8990: 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20  urate but it.** 
89a0: 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20  is often close. 
89b0: 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   The underlying 
89c0: 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65  VFS might choose
89d0: 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20   to preallocate 
89e0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
89f0: 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20   space based on 
8a00: 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64  this hint in ord
8a10: 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65  er to help write
8a20: 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  s to the databas
8a30: 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61  e.** file run fa
8a40: 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ster..**.** <li>
8a50: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  [[SQLITE_FCNTL_C
8a60: 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54  HUNK_SIZE]].** T
8a70: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8a80: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63  _CHUNK_SIZE] opc
8a90: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 72  ode is used to r
8aa0: 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65 20  equest that the 
8ab0: 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61  VFS.** extends a
8ac0: 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 65  nd truncates the
8ad0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
8ae0: 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69  n chunks of a si
8af0: 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ze specified.** 
8b00: 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 65  by the user. The
8b10: 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
8b20: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   to [sqlite3_fil
8b30: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f  e_control()] sho
8b40: 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  uld .** point to
8b50: 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70   an integer (typ
8b60: 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e  e int) containin
8b70: 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d  g the new chunk-
8b80: 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66  size to use.** f
8b90: 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64  or the nominated
8ba0: 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63   database. Alloc
8bb0: 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 66  ating database f
8bc0: 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72  ile space in lar
8bd0: 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61  ge.** chunks (sa
8be0: 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29  y 1MB at a time)
8bf0: 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c  , may reduce fil
8c00: 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e  e-system fragmen
8c10: 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d  tation and.** im
8c20: 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63  prove performanc
8c30: 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d  e on some system
8c40: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
8c50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
8c60: 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68  _POINTER]].** Th
8c70: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8c80: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70  FILE_POINTER] op
8c90: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
8ca0: 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72  obtain a pointer
8cb0: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
8cc0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
8cd0: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
8ce0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
8cf0: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
8d00: 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b  tion.  See the [
8d10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8d20: 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74  trol()] document
8d30: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64  ation for.** add
8d40: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
8d50: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ion..**.** <li>[
8d60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
8d70: 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20  NC_OMITTED]].** 
8d80: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  ^(The [SQLITE_FC
8d90: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
8da0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65  ] opcode is gene
8db0: 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  rated internally
8dc0: 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e   by.** SQLite an
8dd0: 64 20 73 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46  d sent to all VF
8de0: 53 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  Ses in place of 
8df0: 61 20 63 61 6c 6c 20 74 6f 20 74 68 65 20 78 53  a call to the xS
8e00: 79 6e 63 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68  ync method.** wh
8e10: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
8e20: 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b  connection has [
8e30: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
8e40: 75 73 5d 20 73 65 74 20 74 6f 20 4f 46 46 2e 29  us] set to OFF.)
8e50: 5e 0a 2a 2a 20 53 6f 6d 65 20 73 70 65 63 69 61  ^.** Some specia
8e60: 6c 69 7a 65 64 20 56 46 53 65 73 20 6e 65 65 64  lized VFSes need
8e70: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 69 6e 20   this signal in 
8e80: 6f 72 64 65 72 20 74 6f 20 6f 70 65 72 61 74 65  order to operate
8e90: 20 63 6f 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68   correctly.** wh
8ea0: 65 6e 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  en [PRAGMA synch
8eb0: 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20  ronous | PRAGMA 
8ec0: 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d  synchronous=OFF]
8ed0: 20 69 73 20 73 65 74 2c 20 62 75 74 20 6d 6f 73   is set, but mos
8ee0: 74 20 0a 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e  t .** VFSes do n
8ef0: 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  ot need this sig
8f00: 6e 61 6c 20 61 6e 64 20 73 68 6f 75 6c 64 20 73  nal and should s
8f10: 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74  ilently ignore t
8f20: 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41  his opcode..** A
8f30: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
8f40: 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c  ld not call [sql
8f50: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8f60: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 0a 2a  l()] with this.*
8f70: 2a 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e  * opcode as doin
8f80: 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74  g so may disrupt
8f90: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f   the operation o
8fa0: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
8fb0: 64 20 56 46 53 65 73 0a 2a 2a 20 74 68 61 74 20  d VFSes.** that 
8fc0: 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20  do require it.  
8fd0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8fe0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
8ff0: 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54  AV_RETRY]].** ^T
9000: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9010: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
9020: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
9030: 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74  to configure aut
9040: 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20  omatic.** retry 
9050: 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72  counts and inter
9060: 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e  vals for certain
9070: 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74   disk I/O operat
9080: 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ions for the.** 
9090: 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e  windows [VFS] in
90a0: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
90b0: 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20  e robustness in 
90c0: 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a  the presence of.
90d0: 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72  ** anti-virus pr
90e0: 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61  ograms.  By defa
90f0: 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73  ult, the windows
9100: 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20   VFS will retry 
9110: 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69  file read,.** fi
9120: 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69  le write, and fi
9130: 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74  le delete operat
9140: 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69  ions up to 10 ti
9150: 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61  mes, with a dela
9160: 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69  y.** of 25 milli
9170: 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74  seconds before t
9180: 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61  he first retry a
9190: 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61  nd with the dela
91a0: 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20  y increasing.** 
91b0: 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c  by an additional
91c0: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
91d0: 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65   with each subse
91e0: 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68  quent retry.  Th
91f0: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c  is.** opcode all
9200: 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61  ows these two va
9210: 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73  lues (10 retries
9220: 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63   and 25 millisec
9230: 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a  onds of delay).*
9240: 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64  * to be adjusted
9250: 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72  .  The values ar
9260: 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c  e changed for al
9270: 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  l database conne
9280: 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e  ctions.** within
9290: 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73   the same proces
92a0: 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  s.  The argument
92b0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
92c0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f   an array of two
92d0: 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65  .** integers whe
92e0: 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74  re the first int
92f0: 65 67 65 72 20 69 20 74 68 65 20 6e 65 77 20 72  eger i the new r
9300: 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74  etry count and t
9310: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74  he second.** int
9320: 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61  eger is the dela
9330: 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e  y.  If either in
9340: 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76  teger is negativ
9350: 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74  e, then the sett
9360: 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ing.** is not ch
9370: 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61  anged but instea
9380: 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  d the prior valu
9390: 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e  e of that settin
93a0: 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20  g is written.** 
93b0: 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65  into the array e
93c0: 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74  ntry, allowing t
93d0: 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79  he current retry
93e0: 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a   settings to be.
93f0: 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e  ** interrogated.
9400: 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61    The zDbName pa
9410: 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72  rameter is ignor
9420: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
9430: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
9440: 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54  SIST_WAL]].** ^T
9450: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9460: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70  _PERSIST_WAL] op
9470: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
9480: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
9490: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b  .** persistent [
94a0: 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61  WAL | Write Ahea
94b0: 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20  d Log] setting. 
94c0: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
94d0: 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72   auxiliary.** wr
94e0: 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e  ite ahead log an
94f0: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
9500: 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74  files used for t
9510: 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
9520: 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61  ol.** are automa
9530: 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
9540: 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20  when the latest 
9550: 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68  connection to th
9560: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c  e database.** cl
9570: 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70  oses.  Setting p
9580: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
9590: 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20  de causes those 
95a0: 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74  files to persist
95b0: 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e   after.** close.
95c0: 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65    Persisting the
95d0: 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c   files is useful
95e0: 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63   when other proc
95f0: 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  esses that do no
9600: 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20  t.** have write 
9610: 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68  permission on th
9620: 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74  e directory cont
9630: 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  aining the datab
9640: 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a  ase file want.**
9650: 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74   to read the dat
9660: 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74  abase file, as t
9670: 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65  he WAL and share
9680: 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d  d memory files m
9690: 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20  ust exist.** in 
96a0: 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61  order for the da
96b0: 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61  tabase to be rea
96c0: 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72  dable.  The four
96d0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
96e0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
96f0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
9700: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
9710: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
9720: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
9730: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
9740: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70  s 0 to disable p
9750: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
9760: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
9770: 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20  e persistent.** 
9780: 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  WAL mode.  If th
9790: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
97a0: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
97b0: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
97c0: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20   current.** WAL 
97d0: 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74  persistence sett
97e0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
97f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
9800: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
9810: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
9820: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
9830: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  AFE_OVERWRITE] o
9840: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9850: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68   set or query th
9860: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20  e.** persistent 
9870: 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77  "powersafe-overw
9880: 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20  rite" or "PSOW" 
9890: 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53  setting.  The PS
98a0: 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65  OW setting.** de
98b0: 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51  termines the [SQ
98c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
98d0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
98e0: 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44  bit of the.** xD
98f0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
9900: 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68  tics methods. Th
9910: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
9920: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
9930: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9940: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
9950: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
9960: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
9970: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
9980: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
9990: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
99a0: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
99b0: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
99c0: 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  .** mode.  If th
99d0: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
99e0: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
99f0: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
9a00: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f   current.** zero
9a10: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74  -damage mode set
9a20: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ting..**.** <li>
9a30: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  [[SQLITE_FCNTL_O
9a40: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
9a50: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9a60: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
9a70: 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  de is invoked by
9a80: 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70   SQLite after op
9a90: 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65  ening.** a write
9aa0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20   transaction to 
9ab0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75  indicate that, u
9ac0: 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c  nless it is roll
9ad0: 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65  ed back for some
9ae0: 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20  .** reason, the 
9af0: 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20  entire database 
9b00: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65  file will be ove
9b10: 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20  rwritten by the 
9b20: 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e  current .** tran
9b30: 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73  saction. This is
9b40: 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20   used by VACUUM 
9b50: 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
9b60: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9b70: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a  CNTL_VFSNAME]].*
9b80: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9b90: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70  CNTL_VFSNAME] op
9ba0: 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64  code can be used
9bb0: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e   to obtain the n
9bc0: 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b  ames of.** all [
9bd0: 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46  VFSes] in the VF
9be0: 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61  S stack.  The na
9bf0: 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56  mes are of all V
9c00: 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65  FS shims and the
9c10: 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d  .** final bottom
9c20: 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77  -level VFS are w
9c30: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
9c40: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
9c50: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
9c60: 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20  lloc()] and the 
9c70: 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64  result is stored
9c80: 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61   in the char* va
9c90: 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74  riable.** that t
9ca0: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
9cb0: 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ter of [sqlite3_
9cc0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
9cd0: 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68  points to..** Th
9ce0: 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70  e caller is resp
9cf0: 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65  onsible for free
9d00: 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77  ing the memory w
9d10: 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69  hen done.  As wi
9d20: 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63  th.** all file-c
9d30: 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20  ontrol actions, 
9d40: 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72  there is no guar
9d50: 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20  antee that this 
9d60: 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  will actually.**
9d70: 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43   do anything.  C
9d80: 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e  allers should in
9d90: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61  itialize the cha
9da0: 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61  r* variable to a
9db0: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
9dc0: 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69   in case this fi
9dd0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f  le-control is no
9de0: 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20  t implemented.  
9df0: 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  This file-contro
9e00: 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64  l.** is intended
9e10: 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20   for diagnostic 
9e20: 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  use only..**.** 
9e30: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9e40: 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e  TL_PRAGMA]].** ^
9e50: 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47  Whenever a [PRAG
9e60: 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  MA] statement is
9e70: 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c   parsed, an [SQL
9e80: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
9e90: 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  ] .** file contr
9ea0: 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68  ol is sent to th
9eb0: 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f  e open [sqlite3_
9ec0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72  file] object cor
9ed0: 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f  responding.** to
9ee0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
9ef0: 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  le to which the 
9f00: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
9f10: 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72   refers. ^The ar
9f20: 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65  gument.** to the
9f30: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
9f40: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
9f50: 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20  rol is an array 
9f60: 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  of.** pointers t
9f70: 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a  o strings (char*
9f80: 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  *) in which the 
9f90: 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f  second element o
9fa0: 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69  f the array.** i
9fb0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
9fc0: 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65  e pragma and the
9fd0: 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69   third element i
9fe0: 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
9ff0: 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20  o the.** pragma 
a000: 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70  or NULL if the p
a010: 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67  ragma has no arg
a020: 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e  ument.  ^The han
a030: 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b  dler for an.** [
a040: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a050: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
a060: 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79  l can optionally
a070: 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74 20   make the first 
a080: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68  element.** of th
a090: 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e  e char** argumen
a0a0: 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  t point to a str
a0b0: 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ing obtained fro
a0c0: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  m [sqlite3_mprin
a0d0: 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20  tf()].** or the 
a0e0: 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74  equivalent and t
a0f0: 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  hat string will 
a100: 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c  become the resul
a110: 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20  t of the pragma 
a120: 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  or.** the error 
a130: 6d 65 73 73 61 67 65 20 69 66 20 74 68 65 20 70  message if the p
a140: 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66  ragma fails. ^If
a150: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
a160: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
a170: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
a180: 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ns [SQLITE_NOTFO
a190: 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61  UND], then norma
a1a0: 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70  l .** [PRAGMA] p
a1b0: 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e  rocessing contin
a1c0: 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53  ues.  ^If the [S
a1d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a1e0: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  MA].** file cont
a1f0: 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  rol returns [SQL
a200: 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68  ITE_OK], then th
a210: 65 20 70 61 72 73 65 72 20 61 73 73 75 6d 65 73  e parser assumes
a220: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53   that the.** VFS
a230: 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65   has handled the
a240: 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61   PRAGMA itself a
a250: 6e 64 20 74 68 65 20 70 61 72 73 65 72 20 67 65  nd the parser ge
a260: 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a  nerates a no-op.
a270: 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
a280: 65 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ement.  ^If the 
a290: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a2a0: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
a2b0: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ol returns.** an
a2c0: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74  y result code ot
a2d0: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
a2e0: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  _OK] or [SQLITE_
a2f0: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20  NOTFOUND], that 
a300: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68  means.** that th
a310: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65  e VFS encountere
a320: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65  d an error while
a330: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50   handling the [P
a340: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a  RAGMA] and the.*
a350: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66  * compilation of
a360: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c   the PRAGMA fail
a370: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  s with an error.
a380: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46    ^The [SQLITE_F
a390: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
a3a0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63  file control occ
a3b0: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e  urs at the begin
a3c0: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73  ning of pragma s
a3d0: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69  tatement analysi
a3e0: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69  s and so.** it i
a3f0: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69  s able to overri
a400: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41  de built-in [PRA
a410: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  GMA] statements.
a420: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a430: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
a440: 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 69 73  NDLER]].** ^This
a450: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61   file-control ma
a460: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20  y be invoked by 
a470: 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61  SQLite on the da
a480: 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64  tabase file hand
a490: 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66  le.** shortly af
a4a0: 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64  ter it is opened
a4b0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
a4c0: 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46  vide a custom VF
a4d0: 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a  S with access.**
a4e0: 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   to the connecti
a4f0: 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  ons busy-handler
a500: 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61   callback. The a
a510: 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79  rgument is of ty
a520: 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20  pe (void **).** 
a530: 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  - an array of tw
a540: 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65  o (void *) value
a550: 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f  s. The first (vo
a560: 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70  id *) actually p
a570: 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75  oints.** to a fu
a580: 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28  nction of type (
a590: 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29  int (*)(void *))
a5a0: 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  . In order to in
a5b0: 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74  voke the connect
a5c0: 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e  ions.** busy-han
a5d0: 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74  dler, this funct
a5e0: 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e  ion should be in
a5f0: 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73  voked with the s
a600: 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69  econd (void *) i
a610: 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61  n.** the array a
a620: 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d  s the only argum
a630: 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72  ent. If it retur
a640: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
a650: 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  n the operation.
a660: 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
a670: 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75  ried. If it retu
a680: 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75  rns zero, the cu
a690: 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20  stom VFS should 
a6a0: 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63  abandon the.** c
a6b0: 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e  urrent operation
a6c0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a6d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
a6e0: 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70  ILENAME]].** ^Ap
a6f0: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e  plication can in
a700: 76 6f 6b 65 20 74 68 69 73 20 66 69 6c 65 2d 63  voke this file-c
a710: 6f 6e 74 72 6f 6c 20 74 6f 20 68 61 76 65 20 53  ontrol to have S
a720: 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 61  QLite generate a
a730: 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
a740: 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65  lename using the
a750: 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20   same algorithm 
a760: 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64  that is followed
a770: 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20   to generate.** 
a780: 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61  temporary filena
a790: 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62  mes for TEMP tab
a7a0: 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e  les and other in
a7b0: 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68  ternal uses.  Th
a7c0: 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  e.** argument sh
a7d0: 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a  ould be a char**
a7e0: 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66   which will be f
a7f0: 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 66  illed with the f
a800: 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74  ilename.** writt
a810: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
a820: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
a830: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
a840: 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f    The caller sho
a850: 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73  uld.** invoke [s
a860: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
a870: 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20  n the result to 
a880: 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c  avoid a memory l
a890: 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e  eak..**.** </ul>
a8a0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
a8b0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
a8c0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
a8d0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
a8e0: 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_GET_LOCKPROXYF
a8f0: 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ILE             
a900: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
a910: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
a920: 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 33  LE             3
a930: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a940: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
a950: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a                4.
a960: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
a970: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20  CNTL_SIZE_HINT  
a980: 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
a990: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
a9a0: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20  NTL_CHUNK_SIZE  
a9b0: 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
a9c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
a9d0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20  TL_FILE_POINTER 
a9e0: 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
a9f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
aa00: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20  L_SYNC_OMITTED  
aa10: 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66            8.#def
aa20: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
aa30: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20  _WIN32_AV_RETRY 
aa40: 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
aa50: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
aa60: 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20  PERSIST_WAL     
aa70: 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e         10.#defin
aa80: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  e SQLITE_FCNTL_O
aa90: 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20  VERWRITE        
aaa0: 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65        11.#define
aab0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46   SQLITE_FCNTL_VF
aac0: 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  SNAME           
aad0: 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20       12.#define 
aae0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
aaf0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
ab00: 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53      13.#define S
ab10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
ab20: 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
ab30: 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51     14.#define SQ
ab40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
ab50: 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20  ANDLER          
ab60: 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c    15.#define SQL
ab70: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
ab80: 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  LENAME          
ab90: 20 31 36 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   16../*.** CAPI3
aba0: 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c  REF: Mutex Handl
abb0: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65  e.**.** The mute
abc0: 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20  x module within 
abd0: 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b  SQLite defines [
abe0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74  sqlite3_mutex] t
abf0: 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72  o be an.** abstr
ac00: 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d  act type for a m
ac10: 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68  utex object.  Th
ac20: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65  e SQLite core ne
ac30: 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20  ver looks.** at 
ac40: 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
ac50: 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  resentation of a
ac60: 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  n [sqlite3_mutex
ac70: 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64  ].  It only.** d
ac80: 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65  eals with pointe
ac90: 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  rs to the [sqlit
aca0: 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74  e3_mutex] object
acb0: 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20  ..**.** Mutexes 
acc0: 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  are created usin
acd0: 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
ace0: 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79  _alloc()]..*/.ty
acf0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
ad00: 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74  ite3_mutex sqlit
ad10: 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a  e3_mutex;../*.**
ad20: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
ad30: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a  terface Object.*
ad40: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
ad50: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
ad60: 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  vfs object defin
ad70: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
ad80: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
ad90: 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20  SQLite core and 
ada0: 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f  the underlying o
adb0: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
adc0: 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69    The "vfs".** i
add0: 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
ade0: 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20  e object stands 
adf0: 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c  for "virtual fil
ae00: 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a  e system".  See.
ae10: 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46  ** the [VFS | VF
ae20: 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  S documentation]
ae30: 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66   for further inf
ae40: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
ae50: 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  The value of the
ae60: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
ae70: 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62  is initially 1 b
ae80: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
ae90: 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65   in.** future ve
aea0: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
aeb0: 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69  .  Additional fi
aec0: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
aed0: 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20  nded to this.** 
aee0: 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20  object when the 
aef0: 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69  iVersion value i
af00: 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f  s increased.  No
af10: 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75  te that the stru
af20: 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20  cture.** of the 
af30: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
af40: 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ct changes in th
af50: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
af60: 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20  tween.** SQLite 
af70: 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e  version 3.5.9 an
af80: 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20  d 3.6.0 and yet 
af90: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
afa0: 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f  ld was not.** mo
afb0: 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  dified..**.** Th
afc0: 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64  e szOsFile field
afd0: 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
afe0: 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b  the subclassed [
aff0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a  sqlite3_file].**
b000: 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20   structure used 
b010: 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78  by this VFS.  mx
b020: 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20  Pathname is the 
b030: 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
b040: 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20  f.** a pathname 
b050: 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a  in this VFS..**.
b060: 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71  ** Registered sq
b070: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
b080: 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20  s are kept on a 
b090: 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d  linked list form
b0a0: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65  ed by.** the pNe
b0b0: 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  xt pointer.  The
b0c0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65   [sqlite3_vfs_re
b0d0: 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64  gister()].** and
b0e0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e   [sqlite3_vfs_un
b0f0: 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65  register()] inte
b100: 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68  rfaces manage th
b110: 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20  is list.** in a 
b120: 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e  thread-safe way.
b130: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
b140: 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72  fs_find()] inter
b150: 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73  face.** searches
b160: 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74   the list.  Neit
b170: 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  her the applicat
b180: 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65  ion code nor the
b190: 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   VFS.** implemen
b1a0: 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  tation should us
b1b0: 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  e the pNext poin
b1c0: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ter..**.** The p
b1d0: 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68  Next field is th
b1e0: 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20  e only field in 
b1f0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
b200: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61  ** structure tha
b210: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76  t SQLite will ev
b220: 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69  er modify.  SQLi
b230: 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63  te will only acc
b240: 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79  ess.** or modify
b250: 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c   this field whil
b260: 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74  e holding a part
b270: 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75  icular static mu
b280: 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  tex..** The appl
b290: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
b2a0: 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74  ever modify anyt
b2b0: 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20  hing within the 
b2c0: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f  sqlite3_vfs.** o
b2d0: 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f  bject once the o
b2e0: 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72  bject has been r
b2f0: 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a  egistered..**.**
b300: 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64   The zName field
b310: 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20   holds the name 
b320: 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c  of the VFS modul
b330: 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73  e.  The name mus
b340: 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61  t.** be unique a
b350: 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f  cross all VFS mo
b360: 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73  dules..**.** [[s
b370: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
b380: 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  ]].** ^SQLite gu
b390: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
b3a0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
b3b0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
b3c0: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
b3d0: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
b3e0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
b3f0: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
b400: 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70  ame() with an op
b410: 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64  tional suffix ad
b420: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75  ded..** ^If a su
b430: 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f  ffix is added to
b440: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
b450: 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c  arameter, it wil
b460: 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20  l.** consist of 
b470: 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61  a single "-" cha
b480: 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20  racter followed 
b490: 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a  by no more than.
b4a0: 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72  ** 11 alphanumer
b4b0: 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68  ic and/or "-" ch
b4c0: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51  aracters..** ^SQ
b4d0: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
b4e0: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
b4f0: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
b500: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
b510: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
b520: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
b530: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74  ed. Because of t
b540: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
b550: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ence,.** the [sq
b560: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
b570: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
b580: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
b590: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
b5a0: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
b5b0: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
b5c0: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
b5d0: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
b5e0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
b5f0: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
b600: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
b610: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65  pen.** must inve
b620: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  nt its own tempo
b630: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
b640: 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76  e file.  ^Whenev
b650: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65  er the .** xFile
b660: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
b670: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61  s NULL it will a
b680: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20  lso be the case 
b690: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67  that the.** flag
b6a0: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c  s parameter will
b6b0: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
b6c0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
b6d0: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  OSE]..**.** The 
b6e0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
b6f0: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64  o xOpen() includ
b700: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20  es all bits set 
b710: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20  in.** the flags 
b720: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
b730: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
b740: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    Or if [sqlite3
b750: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b  _open()].** or [
b760: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
b770: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  ] is used, then 
b780: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61  flags includes a
b790: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49  t least.** [SQLI
b7a0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
b7b0: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
b7c0: 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49  N_CREATE]. .** I
b7d0: 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20  f xOpen() opens 
b7e0: 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79  a file read-only
b7f0: 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70   then it sets *p
b800: 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69  OutFlags to.** i
b810: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
b820: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20  PEN_READONLY].  
b830: 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70  Other bits in *p
b840: 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20  OutFlags may be 
b850: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c  set..**.** ^(SQL
b860: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
b870: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
b880: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
b890: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
b8a0: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
b8b0: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
b8c0: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a  ng opened:.**.**
b8d0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b   <ul>.** <li>  [
b8e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
b8f0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
b900: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
b910: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
b920: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
b930: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  EMP_DB].** <li> 
b940: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
b950: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  MP_JOURNAL].** <
b960: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
b970: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a  N_TRANSIENT_DB].
b980: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
b990: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
b9a0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
b9b0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
b9c0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
b9d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41   [SQLITE_OPEN_WA
b9e0: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  L].** </ul>)^.**
b9f0: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
ba00: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
ba10: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
ba20: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
ba30: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
ba40: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
ba50: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
ba60: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
ba70: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
ba80: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
ba90: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
baa0: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
bab0: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
bac0: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
bad0: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
bae0: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
baf0: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
bb00: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
bb10: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
bb20: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
bb30: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
bb40: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
bb50: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
bb60: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
bb70: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
bb80: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
bb90: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
bba0: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
bbb0: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
bbc0: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
bbd0: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
bbe0: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
bbf0: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
bc00: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
bc10: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
bc20: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
bc30: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
bc40: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
bc50: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
bc60: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
bc70: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
bc80: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
bc90: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
bca0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
bcb0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
bcc0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
bcd0: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
bce0: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
bcf0: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
bd00: 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53  closed.  ^The [S
bd10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
bd20: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c  EONCLOSE].** wil
bd30: 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d  l be set for TEM
bd40: 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20  P databases and 
bd50: 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20  their journals, 
bd60: 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74  transient.** dat
bd70: 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a  abases, and subj
bd80: 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ournals..**.** ^
bd90: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
bda0: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
bdb0: 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
bdc0: 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a  in conjunction.*
bdd0: 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
bde0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20  TE_OPEN_CREATE] 
bdf0: 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20  flag, which are 
be00: 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a  both directly.**
be10: 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68   analogous to th
be20: 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43  e O_EXCL and O_C
be30: 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68  REAT flags of th
be40: 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a  e POSIX open().*
be50: 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49  * API.  The SQLI
be60: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
be70: 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69  E flag, when pai
be80: 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  red with the .**
be90: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
bea0: 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20  ATE, is used to 
beb0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69  indicate that fi
bec0: 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  le should always
bed0: 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20  .** be created, 
bee0: 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61  and that it is a
bef0: 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c  n error if it al
bf00: 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a  ready exists..**
bf10: 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69   It is <i>not</i
bf20: 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  > used to indica
bf30: 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  te the file shou
bf40: 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a  ld be opened .**
bf50: 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61   for exclusive a
bf60: 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74  ccess..**.** ^At
bf70: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
bf80: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
bf90: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
bfa0: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
bfb0: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
bfc0: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
bfd0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
bfe0: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
bff0: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
c000: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
c010: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
c020: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
c030: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
c040: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
c050: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a  in.  Note that.*
c060: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  * the xOpen meth
c070: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20  od must set the 
c080: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
c090: 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a  thods to either.
c0a0: 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69  ** a valid [sqli
c0b0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
c0c0: 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c  object or to NUL
c0d0: 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64  L.  xOpen must d
c0e0: 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69  o.** this even i
c0f0: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73  f the open fails
c100: 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74  .  SQLite expect
c110: 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74  s that the sqlit
c120: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
c130: 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c  .** element will
c140: 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20   be valid after 
c150: 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65  xOpen returns re
c160: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
c170: 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61  success.** or fa
c180: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70  ilure of the xOp
c190: 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b  en call..**.** [
c1a0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63  [sqlite3_vfs.xAc
c1b0: 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66  cess]].** ^The f
c1c0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
c1d0: 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62   xAccess() may b
c1e0: 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  e [SQLITE_ACCESS
c1f0: 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74  _EXISTS].** to t
c200: 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73  est for the exis
c210: 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c  tence of a file,
c220: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
c230: 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f  SS_READWRITE] to
c240: 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72  .** test whether
c250: 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61   a file is reada
c260: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
c270: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
c280: 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20  ESS_READ].** to 
c290: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
c2a0: 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20  ile is at least 
c2b0: 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20  readable.   The 
c2c0: 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a  file can be a.**
c2d0: 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
c2e0: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  * ^SQLite will a
c2f0: 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61  lways allocate a
c300: 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61  t least mxPathna
c310: 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74  me+1 bytes for t
c320: 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66  he.** output buf
c330: 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  fer xFullPathnam
c340: 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69  e.  The exact si
c350: 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74  ze of the output
c360: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c   buffer.** is al
c370: 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70  so passed as a p
c380: 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68  arameter to both
c390: 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68    methods. If th
c3a0: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
c3b0: 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20  ** is not large 
c3c0: 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f  enough, [SQLITE_
c3d0: 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64  CANTOPEN] should
c3e0: 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69   be returned. Si
c3f0: 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68  nce this is.** h
c400: 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61  andled as a fata
c410: 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74  l error by SQLit
c420: 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74  e, vfs implement
c430: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e  ations should en
c440: 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65  deavor.** to pre
c450: 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74  vent this by set
c460: 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20  ting mxPathname 
c470: 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c  to a sufficientl
c480: 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a  y large value..*
c490: 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  *.** The xRandom
c4a0: 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29  ness(), xSleep()
c4b0: 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  , xCurrentTime()
c4c0: 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69  , and xCurrentTi
c4d0: 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74  meInt64().** int
c4e0: 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20  erfaces are not 
c4f0: 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20  strictly a part 
c500: 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65  of the filesyste
c510: 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a  m, but they are.
c520: 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ** included in t
c530: 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65  he VFS structure
c540: 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73   for completenes
c550: 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  s..** The xRando
c560: 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e  mness() function
c570: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74   attempts to ret
c580: 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73  urn nBytes bytes
c590: 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c  .** of good-qual
c5a0: 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69  ity randomness i
c5b0: 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72  nto zOut.  The r
c5c0: 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a  eturn value is.*
c5d0: 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d  * the actual num
c5e0: 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20  ber of bytes of 
c5f0: 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
c600: 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65  ned..** The xSle
c610: 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73  ep() method caus
c620: 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74  es the calling t
c630: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66  hread to sleep f
c640: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74  or at.** least t
c650: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63  he number of mic
c660: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e  roseconds given.
c670: 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54    ^The xCurrentT
c680: 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ime().** method 
c690: 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e  returns a Julian
c6a0: 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20   Day Number for 
c6b0: 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65  the current date
c6c0: 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20   and time as.** 
c6d0: 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
c6e0: 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20   value..** ^The 
c6f0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
c700: 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  4() method retur
c710: 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65  ns, as an intege
c720: 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a  r, the Julian.**
c730: 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74   Day Number mult
c740: 69 70 6c 69 65 64 20 62 79 20 38 36 34 30 30 30  iplied by 864000
c750: 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f  00 (the number o
c760: 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69  f milliseconds i
c770: 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20  n .** a 24-hour 
c780: 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69  day).  .** ^SQLi
c790: 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
c7a0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
c7b0: 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65  4() method to ge
c7c0: 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  t the current.**
c7d0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69   date and time i
c7e0: 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73  f that method is
c7f0: 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69   available (if i
c800: 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20  Version is 2 or 
c810: 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20  .** greater and 
c820: 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
c830: 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
c840: 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20  ) and will fall 
c850: 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72  back.** to xCurr
c860: 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43 75  entTime() if xCu
c870: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
c880: 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
c890: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74  .**.** ^The xSet
c8a0: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47  SystemCall(), xG
c8b0: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20  etSystemCall(), 
c8c0: 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43  and xNestSystemC
c8d0: 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73  all() interfaces
c8e0: 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64  .** are not used
c8f0: 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 20 63   by the SQLite c
c900: 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69  ore.  These opti
c910: 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20  onal interfaces 
c920: 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  are provided.** 
c930: 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f  by some VFSes to
c940: 20 66 61 63 69 6c 69 74 61 74 65 20 74 65 73 74   facilitate test
c950: 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20 63  ing of the VFS c
c960: 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69  ode. By overridi
c970: 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61  ng .** system ca
c980: 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f  lls with functio
c990: 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e  ns under its con
c9a0: 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f  trol, a test pro
c9b0: 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75  gram can.** simu
c9c0: 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20  late faults and 
c9d0: 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73  error conditions
c9e0: 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65   that would othe
c9f0: 72 77 69 73 65 20 62 65 20 64 69 66 66 69 63 75  rwise be difficu
ca00: 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69  lt.** or impossi
ca10: 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20  ble to induce.  
ca20: 54 68 65 20 73 65 74 20 6f 66 20 73 79 73 74 65  The set of syste
ca30: 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e  m calls that can
ca40: 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a   be overridden.*
ca50: 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e  * varies from on
ca60: 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72  e VFS to another
ca70: 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76  , and from one v
ca80: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61  ersion of the sa
ca90: 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a  me VFS to the.**
caa0: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
cab0: 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74 68  ions that use th
cac0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
cad0: 75 73 74 20 62 65 20 70 72 65 70 61 72 65 64 20  ust be prepared 
cae0: 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c  for any.** or al
caf0: 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72  l of these inter
cb00: 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c  faces to be NULL
cb10: 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62 65   or for their be
cb20: 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65  havior to change
cb30: 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c  .** from one rel
cb40: 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74  ease to the next
cb50: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
cb60: 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74  must not attempt
cb70: 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e   to access.** an
cb80: 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f  y of these metho
cb90: 64 73 20 69 66 20 74 68 65 20 69 56 65 72 73 69  ds if the iVersi
cba0: 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69 73  on of the VFS is
cbb0: 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f   less than 3..*/
cbc0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
cbd0: 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69  sqlite3_vfs sqli
cbe0: 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66  te3_vfs;.typedef
cbf0: 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
cc00: 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69  syscall_ptr)(voi
cc10: 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  d);.struct sqlit
cc20: 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69  e3_vfs {.  int i
cc30: 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20  Version;        
cc40: 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65      /* Structure
cc50: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20   version number 
cc60: 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f  (currently 3) */
cc70: 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b  .  int szOsFile;
cc80: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
cc90: 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65  ize of subclasse
cca0: 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a  d sqlite3_file *
ccb0: 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61  /.  int mxPathna
ccc0: 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  me;          /* 
ccd0: 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74  Maximum file pat
cce0: 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a  hname length */.
ccf0: 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70    sqlite3_vfs *p
cd00: 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65  Next;      /* Ne
cd10: 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46  xt registered VF
cd20: 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  S */.  const cha
cd30: 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20  r *zName;       
cd40: 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20  /* Name of this 
cd50: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
cd60: 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tem */.  void *p
cd70: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
cd80: 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20    /* Pointer to 
cd90: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63  application-spec
cda0: 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69  ific data */.  i
cdb0: 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
cdc0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
cdd0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
cde0: 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20  ite3_file*,.    
cdf0: 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66             int f
ce00: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46  lags, int *pOutF
ce10: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
ce20: 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f  Delete)(sqlite3_
ce30: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
ce40: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e   *zName, int syn
ce50: 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  cDir);.  int (*x
ce60: 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f  Access)(sqlite3_
ce70: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
ce80: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61   *zName, int fla
ce90: 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  gs, int *pResOut
cea0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c  );.  int (*xFull
ceb0: 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65  Pathname)(sqlite
cec0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
ced0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e  ar *zName, int n
cee0: 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  Out, char *zOut)
cef0: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f  ;.  void *(*xDlO
cf00: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
cf10: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
cf20: 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69  Filename);.  voi
cf30: 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71  d (*xDlError)(sq
cf40: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
cf50: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72  nByte, char *zEr
cf60: 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a  rMsg);.  void (*
cf70: 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65  (*xDlSym)(sqlite
cf80: 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f  3_vfs*,void*, co
cf90: 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f  nst char *zSymbo
cfa0: 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69  l))(void);.  voi
cfb0: 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71  d (*xDlClose)(sq
cfc0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64  lite3_vfs*, void
cfd0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e  *);.  int (*xRan
cfe0: 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33  domness)(sqlite3
cff0: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
d000: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
d010: 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73   int (*xSleep)(s
d020: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
d030: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a   microseconds);.
d040: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
d050: 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  Time)(sqlite3_vf
d060: 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20  s*, double*);.  
d070: 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72  int (*xGetLastEr
d080: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
d090: 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b  *, int, char *);
d0a0: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
d0b0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
d0c0: 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66   in version 1 of
d0d0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
d0e0: 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69  object.  ** defi
d0f0: 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74  nition.  Those t
d100: 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61  hat follow are a
d110: 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20  dded in version 
d120: 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a  2 or later.  */.
d130: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
d140: 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74  TimeInt64)(sqlit
d150: 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33  e3_vfs*, sqlite3
d160: 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20  _int64*);.  /*. 
d170: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
d180: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
d190: 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66  sions 1 and 2 of
d1a0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
d1b0: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f  object..  ** Tho
d1c0: 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72  se below are for
d1d0: 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67   version 3 and g
d1e0: 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69  reater..  */.  i
d1f0: 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43  nt (*xSetSystemC
d200: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
d210: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
d220: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79  Name, sqlite3_sy
d230: 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71  scall_ptr);.  sq
d240: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
d250: 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61  r (*xGetSystemCa
d260: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
d270: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
d280: 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68  ame);.  const ch
d290: 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65  ar *(*xNextSyste
d2a0: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
d2b0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
d2c0: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20  *zName);.  /*.  
d2d0: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
d2e0: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
d2f0: 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33  ions 1 through 3
d300: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
d310: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
d320: 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62  New fields may b
d330: 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69  e appended in fi
d340: 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20  gure versions.  
d350: 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a  The iVersion.  *
d360: 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63  * value will inc
d370: 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20  rement whenever 
d380: 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20  this happens. . 
d390: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
d3a0: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
d3b0: 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46  r the xAccess VF
d3c0: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
d3d0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
d3e0: 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73  stants can be us
d3f0: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
d400: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
d410: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
d420: 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  od of an [sqlite
d430: 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20  3_vfs] object.  
d440: 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a  They determine.*
d450: 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70  * what kind of p
d460: 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78  ermissions the x
d470: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73  Access method is
d480: 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a   looking for..**
d490: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
d4a0: 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20  ESS_EXISTS, the 
d4b0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
d4c0: 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20  * simply checks 
d4d0: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
d4e0: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68   exists..** With
d4f0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
d500: 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41  EADWRITE, the xA
d510: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
d520: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
d530: 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f  he named directo
d540: 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 64 61  ry is both reada
d550: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
d560: 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f  .** (in other wo
d570: 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61  rds, if files ca
d580: 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f  n be added, remo
d590: 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64  ved, and renamed
d5a0: 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64   within.** the d
d5b0: 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68  irectory)..** Th
d5c0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
d5d0: 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61  READWRITE consta
d5e0: 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  nt is currently 
d5f0: 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65  used only by the
d600: 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  .** [temp_store_
d610: 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
d620: 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 63  ], though this c
d630: 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61  ould change in a
d640: 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61   future.** relea
d650: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
d660: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
d670: 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41  ESS_READ, the xA
d680: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
d690: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
d6a0: 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61  he file is reada
d6b0: 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ble.  The SQLITE
d6c0: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e  _ACCESS_READ con
d6d0: 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72  stant is.** curr
d6e0: 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68  ently unused, th
d6f0: 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 62 65  ough it might be
d700: 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 75 72   used in a futur
d710: 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20  e release of.** 
d720: 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
d730: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
d740: 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65  _EXISTS    0.#de
d750: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
d760: 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 20 20  SS_READWRITE 1  
d770: 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41 47   /* Used by PRAG
d780: 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  MA temp_store_di
d790: 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69  rectory */.#defi
d7a0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
d7b0: 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 20 2f  _READ      2   /
d7c0: 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  * Unused */../*.
d7d0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
d7e0: 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c  gs for the xShmL
d7f0: 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ock VFS method.*
d800: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
d810: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  er constants def
d820: 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73 20  ine the various 
d830: 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f  locking operatio
d840: 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79  ns.** allowed by
d850: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   the xShmLock me
d860: 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  thod of [sqlite3
d870: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54  _io_methods].  T
d880: 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  he.** following 
d890: 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67  are the only leg
d8a0: 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  al combinations 
d8b0: 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a  of flags to the.
d8c0: 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  ** xShmLock meth
d8d0: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
d8e0: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
d8f0: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
d900: 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c  _SHM_SHARED.** <
d910: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
d920: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
d930: 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c  M_EXCLUSIVE.** <
d940: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
d950: 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  UNLOCK | SQLITE_
d960: 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c  SHM_SHARED.** <l
d970: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  i>  SQLITE_SHM_U
d980: 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  NLOCK | SQLITE_S
d990: 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20  HM_EXCLUSIVE.** 
d9a0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  </ul>.**.** When
d9b0: 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20   unlocking, the 
d9c0: 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45  same SHARED or E
d9d0: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75  XCLUSIVE flag mu
d9e0: 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 20 61  st be supplied a
d9f0: 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e  s.** was given n
da00: 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
da10: 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a  ing lock.  .**.*
da20: 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
da30: 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69  ethod can transi
da40: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c  tion between unl
da50: 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44  ocked and SHARED
da60: 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75   or.** between u
da70: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c  nlocked and EXCL
da80: 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f  USIVE.  It canno
da90: 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  t transition bet
daa0: 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61  ween SHARED.** a
dab0: 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f  nd EXCLUSIVE..*/
dac0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dad0: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  SHM_UNLOCK      
dae0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
daf0: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20  E_SHM_LOCK      
db00: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
db10: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20  ITE_SHM_SHARED  
db20: 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
db30: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
db40: 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20  IVE    8../*.** 
db50: 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75  CAPI3REF: Maximu
db60: 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78  m xShmLock index
db70: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
db80: 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73  ock method on [s
db90: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
dba0: 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65  s] may use value
dbb0: 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61  s.** between 0 a
dbc0: 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 62 6f  nd this upper bo
dbd0: 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66 73  und as its "offs
dbe0: 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  et" argument..**
dbf0: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
dc00: 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65   will never atte
dc10: 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f  mpt to acquire o
dc20: 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c  r release a.** l
dc30: 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74  ock outside of t
dc40: 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65  his range.*/.#de
dc50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
dc60: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a  NLOCK        8..
dc70: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
dc80: 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20   Initialize The 
dc90: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
dca0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
dcb0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
dcc0: 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a  outine initializ
dcd0: 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  es the.** SQLite
dce0: 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20   library.  ^The 
dcf0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
dd00: 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65  () routine.** de
dd10: 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65  allocates any re
dd20: 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72  sources that wer
dd30: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
dd40: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
dd50: 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e()..** These ro
dd60: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67  utines are desig
dd70: 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72  ned to aid in pr
dd80: 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
dd90: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74  tion and.** shut
dda0: 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64  down on embedded
ddb0: 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73   systems.  Works
ddc0: 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69  tation applicati
ddd0: 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c  ons using.** SQL
dde0: 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20  ite normally do 
ddf0: 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f  not need to invo
de00: 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65  ke either of the
de10: 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
de20: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
de30: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
de40: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
de50: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
de60: 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74  s.** the first t
de70: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
de80: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
de90: 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c  ked during the l
dea0: 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68  ifetime of.** th
deb0: 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  e process, or if
dec0: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
ded0: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
dee0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
def0: 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  voked.** followi
df00: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ng a call to sql
df10: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
df20: 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65    ^(Only an effe
df30: 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66  ctive call.** of
df40: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
df50: 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69  ize() does any i
df60: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20  nitialization.  
df70: 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a  All other calls.
df80: 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  ** are harmless 
df90: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
dfa0: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
dfb0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20  3_shutdown() is 
dfc0: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
dfd0: 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65  all if it is the
dfe0: 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74   first.** call t
dff0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
e000: 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c  wn() since the l
e010: 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ast sqlite3_init
e020: 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c  ialize().  ^(Onl
e030: 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76  y.** an effectiv
e040: 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  e call to sqlite
e050: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65  3_shutdown() doe
e060: 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69  s any deinitiali
e070: 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f  zation..** All o
e080: 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73  ther valid calls
e090: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
e0a0: 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c  down() are harml
e0b0: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
e0c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
e0d0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74  initialize() int
e0e0: 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64  erface is thread
e0f0: 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65  safe, but sqlite
e100: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
e110: 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c  is not.  The sql
e120: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
e130: 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f  interface must o
e140: 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72  nly be called fr
e150: 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74  om a.** single t
e160: 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e  hread.  All open
e170: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
e180: 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20  ctions] must be 
e190: 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a  closed and all.*
e1a0: 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72  * other SQLite r
e1b0: 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65  esources must be
e1c0: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69   deallocated pri
e1d0: 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a  or to invoking.*
e1e0: 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  * sqlite3_shutdo
e1f0: 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e  wn()..**.** Amon
e200: 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20  g other things, 
e210: 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  ^sqlite3_initial
e220: 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b  ize() will invok
e230: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  e.** sqlite3_os_
e240: 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72  init().  Similar
e250: 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75  ly, ^sqlite3_shu
e260: 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20  tdown().** will 
e270: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f  invoke sqlite3_o
e280: 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  s_end()..**.** ^
e290: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
e2a0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
e2b0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
e2c0: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e  _OK] on success.
e2d0: 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65  .** ^If for some
e2e0: 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33   reason, sqlite3
e2f0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
e300: 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69   unable to initi
e310: 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62  alize.** the lib
e320: 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74  rary (perhaps it
e330: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
e340: 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20  locate a needed 
e350: 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a  resource such.**
e360: 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20   as a mutex) it 
e370: 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f  returns an [erro
e380: 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68  r code] other th
e390: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  an [SQLITE_OK]..
e3a0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
e3b0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
e3c0: 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
e3d0: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
e3e0: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51  many other.** SQ
e3f0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
e400: 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69  so that an appli
e410: 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64  cation usually d
e420: 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a  oes not need to.
e430: 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
e440: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
e450: 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78  irectly.  For ex
e460: 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f  ample, [sqlite3_
e470: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73  open()].** calls
e480: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e490: 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c  ize() so the SQL
e4a0: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
e4b0: 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
e4c0: 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64  y.** initialized
e4d0: 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f   when [sqlite3_o
e4e0: 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  pen()] is called
e4f0: 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62   if it has not b
e500: 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a  e initialized.**
e510: 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65   already.  ^Howe
e520: 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69  ver, if SQLite i
e530: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
e540: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  the [SQLITE_OMIT
e550: 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f  _AUTOINIT].** co
e560: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
e570: 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f  n, then the auto
e580: 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73  matic calls to s
e590: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e5a0: 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74  e().** are omitt
e5b0: 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ed and the appli
e5c0: 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c  cation must call
e5d0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e5e0: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a  ize() directly.*
e5f0: 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  * prior to using
e600: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
e610: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f  e interface.  Fo
e620: 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62  r maximum portab
e630: 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20  ility,.** it is 
e640: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
e650: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c   applications al
e660: 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69  ways invoke sqli
e670: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
e680: 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69  .** directly pri
e690: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
e6a0: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
e6b0: 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20  erface.  Future 
e6c0: 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53  releases.** of S
e6d0: 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72  QLite may requir
e6e0: 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65  e this.  In othe
e6f0: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68  r words, the beh
e700: 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a  avior exhibited.
e710: 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
e720: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
e730: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
e740: 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63  OINIT] might bec
e750: 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75  ome the.** defau
e760: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73  lt behavior in s
e770: 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
e780: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
e790: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
e7a0: 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e  os_init() routin
e7b0: 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67  e does operating
e7c0: 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
e7d0: 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  .** initializati
e7e0: 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
e7f0: 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73   library.  The s
e800: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
e810: 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65  ** routine undoe
e820: 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
e830: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
e840: 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b  ).  Typical task
e850: 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62  s.** performed b
e860: 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  y these routines
e870: 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74   include allocat
e880: 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ion or deallocat
e890: 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63  ion.** of static
e8a0: 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74   resources, init
e8b0: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c  ialization of gl
e8c0: 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a  obal variables,.
e8d0: 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20  ** setting up a 
e8e0: 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
e8f0: 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72  _vfs] module, or
e900: 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61   setting up.** a
e910: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
e920: 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71  ration using [sq
e930: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e  lite3_config()].
e940: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
e950: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
e960: 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65  ver invoke eithe
e970: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
e980: 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
e990: 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63  3_os_end() direc
e9a0: 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63  tly.  The applic
e9b0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c  ation should onl
e9c0: 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  y invoke.** sqli
e9d0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
e9e0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75   and sqlite3_shu
e9f0: 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71  tdown().  The sq
ea00: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
ea10: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
ea20: 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63  called automatic
ea30: 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
ea40: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
ea50: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  .** sqlite3_os_e
ea60: 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62  nd() is called b
ea70: 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  y sqlite3_shutdo
ea80: 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61  wn().  Appropria
ea90: 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  te.** implementa
eaa0: 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65  tions for sqlite
eab0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
eac0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
ead0: 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e  .** are built in
eae0: 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69  to SQLite when i
eaf0: 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f  t is compiled fo
eb00: 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c  r Unix, Windows,
eb10: 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65   or OS/2..** Whe
eb20: 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73  n [custom builds
eb30: 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68   | built for oth
eb40: 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a  er platforms].**
eb50: 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c   (using the [SQL
eb60: 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20  ITE_OS_OTHER=1] 
eb70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
eb80: 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c  option) the appl
eb90: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70  ication must sup
eba0: 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69  ply a suitable i
ebb0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  mplementation fo
ebc0: 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  r.** sqlite3_os_
ebd0: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
ebe0: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e  e3_os_end().  An
ebf0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
ec00: 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65  plied.** impleme
ec10: 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
ec20: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20  e3_os_init() or 
ec30: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
ec40: 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20  .** must return 
ec50: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
ec60: 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20  uccess and some 
ec70: 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64  other [error cod
ec80: 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75  e] upon.** failu
ec90: 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  re..*/.int sqlit
eca0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f  e3_initialize(vo
ecb0: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
ecc0: 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b  _shutdown(void);
ecd0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
ece0: 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20  init(void);.int 
ecf0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76  sqlite3_os_end(v
ed00: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
ed10: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69  I3REF: Configuri
ed20: 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ng The SQLite Li
ed30: 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20  brary.**.** The 
ed40: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ed50: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
ed60: 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61  ed to make globa
ed70: 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  l configuration.
ed80: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51  ** changes to SQ
ed90: 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
eda0: 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20   tune SQLite to 
edb0: 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
edc0: 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  ds of.** the app
edd0: 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  lication.  The d
ede0: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
edf0: 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e  tion is recommen
ee00: 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20  ded for most.** 
ee10: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64  applications and
ee20: 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   so this routine
ee30: 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20   is usually not 
ee40: 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69  necessary.  It i
ee50: 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f  s.** provided to
ee60: 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70   support rare ap
ee70: 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20  plications with 
ee80: 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a  unusual needs..*
ee90: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
eea0: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
eeb0: 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ace is not threa
eec0: 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c  dsafe.  The appl
eed0: 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  ication.** must 
eee0: 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f  insure that no o
eef0: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
ef00: 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b  rfaces are invok
ef10: 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74  ed by other.** t
ef20: 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c  hreads while sql
ef30: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
ef40: 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68   running.  Furth
ef50: 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f  ermore, sqlite3_
ef60: 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20  config().** may 
ef70: 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
ef80: 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
ef90: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
efa0: 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
efb0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
efc0: 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
efd0: 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
efe0: 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49  utdown()]..** ^I
eff0: 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  f sqlite3_config
f000: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74  () is called aft
f010: 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  er [sqlite3_init
f020: 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65  ialize()] and be
f030: 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fore.** [sqlite3
f040: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65  _shutdown()] the
f050: 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e  n it will return
f060: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
f070: 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
f080: 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f  , that ^sqlite3_
f090: 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
f0a0: 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
f0b0: 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
f0c0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
f0d0: 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
f0e0: 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
f0f0: 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
f100: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
f110: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
f120: 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
f130: 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74  r.** [configurat
f140: 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74  ion option] that
f150: 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77   determines.** w
f160: 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20  hat property of 
f170: 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20  SQLite is to be 
f180: 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62  configured.  Sub
f190: 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
f1a0: 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64  s.** vary depend
f1b0: 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66  ing on the [conf
f1c0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
f1d0: 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
f1e0: 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
f1f0: 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67  * ^When a config
f200: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
f210: 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63  s set, sqlite3_c
f220: 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20  onfig() returns 
f230: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20  [SQLITE_OK]..** 
f240: 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69  ^If the option i
f250: 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c  s unknown or SQL
f260: 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
f270: 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a   set the option.
f280: 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  ** then this rou
f290: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e  tine returns a n
f2a0: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
f2b0: 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ode]..*/.int sql
f2c0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c  ite3_config(int,
f2d0: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
f2e0: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
f2f0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
f300: 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
f310: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
f320: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
f330: 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63  s used to make c
f340: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
f350: 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61  changes to a [da
f360: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
f370: 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  n].  The interfa
f380: 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ce is similar to
f390: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
f3a0: 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68  fig()] except th
f3b0: 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  at the changes a
f3c0: 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65  pply to a single
f3d0: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
f3e0: 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69  nnection] (speci
f3f0: 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  fied in the firs
f400: 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a  t argument)..**.
f410: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
f420: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
f430: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c  3_db_config(D,V,
f440: 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20  ...)  is the.** 
f450: 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
f460: 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e  _LOOKASIDE | con
f470: 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d  figuration verb]
f480: 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f   - an integer co
f490: 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69  de .** that indi
f4a0: 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65 63  cates what aspec
f4b0: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
f4c0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
f4d0: 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72  s being configur
f4e0: 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e  ed..** Subsequen
f4f0: 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79  t arguments vary
f500: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
f510: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
f520: 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  verb..**.** ^Cal
f530: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  ls to sqlite3_db
f540: 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
f550: 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e   SQLITE_OK if an
f560: 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65  d only if.** the
f570: 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65   call is conside
f580: 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a  red successful..
f590: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
f5a0: 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33  b_config(sqlite3
f5b0: 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b  *, int op, ...);
f5c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f5d0: 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
f5e0: 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a  ion Routines.**.
f5f0: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
f600: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65  f this object de
f610: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
f620: 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69  ace between SQLi
f630: 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65  te.** and low-le
f640: 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
f650: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a  ation routines..
f660: 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  **.** This objec
f670: 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c  t is used in onl
f680: 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74  y one place in t
f690: 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  he SQLite interf
f6a0: 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  ace..** A pointe
f6b0: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
f6c0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
f6d0: 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  is the argument 
f6e0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
f6f0: 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68  onfig()] when th
f700: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
f710: 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51  option is.** [SQ
f720: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
f730: 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  OC] or [SQLITE_C
f740: 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d  ONFIG_GETMALLOC]
f750: 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69  .  .** By creati
f760: 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ng an instance o
f770: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a  f this object.**
f780: 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20   and passing it 
f790: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  to [sqlite3_conf
f7a0: 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
f7b0: 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64  IG_MALLOC]).** d
f7c0: 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  uring configurat
f7d0: 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ion, an applicat
f7e0: 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20  ion can specify 
f7f0: 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
f800: 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
f810: 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f  ion subsystem fo
f820: 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20  r SQLite to use 
f830: 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a  for all of its.*
f840: 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  * dynamic memory
f850: 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   needs..**.** No
f860: 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  te that SQLite c
f870: 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61  omes with severa
f880: 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  l [built-in memo
f890: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a  ry allocators].*
f8a0: 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65  * that are perfe
f8b0: 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f  ctly adequate fo
f8c0: 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69  r the overwhelmi
f8d0: 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61  ng majority of a
f8e0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61  pplications.** a
f8f0: 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a  nd that this obj
f900: 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66  ect is only usef
f910: 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e  ul to a tiny min
f920: 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
f930: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70  tions.** with sp
f940: 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79  ecialized memory
f950: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
f960: 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20  irements.  This 
f970: 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73  object is.** als
f980: 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  o used during te
f990: 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20  sting of SQLite 
f9a0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63  in order to spec
f9b0: 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
f9c0: 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
f9d0: 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75  ocator that simu
f9e0: 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74  lates memory out
f9f0: 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69  -of-memory condi
fa00: 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65  tions in.** orde
fa10: 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74  r to verify that
fa20: 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73   SQLite recovers
fa30: 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d   gracefully from
fa40: 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69   such.** conditi
fa50: 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ons..**.** The x
fa60: 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63  Malloc, xRealloc
fa70: 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68  , and xFree meth
fa80: 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69  ods must work li
fa90: 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63  ke the.** malloc
faa0: 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e  (), realloc() an
fab0: 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f  d free() functio
fac0: 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ns from the stan
fad0: 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
fae0: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
faf0: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73  ntees that the s
fb00: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
fb10: 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73  o.** xRealloc is
fb20: 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20   always a value 
fb30: 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72  returned by a pr
fb40: 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75  ior call to xRou
fb50: 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a  ndup..**.** xSiz
fb60: 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  e should return 
fb70: 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
fb80: 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61  ze of a memory a
fb90: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65  llocation.** pre
fba0: 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64  viously obtained
fbb0: 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72   from xMalloc or
fbc0: 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20   xRealloc.  The 
fbd0: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a  allocated size.*
fbe0: 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c  * is always at l
fbf0: 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74  east as big as t
fc00: 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  he requested siz
fc10: 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  e but may be lar
fc20: 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ger..**.** The x
fc30: 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72  Roundup method r
fc40: 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c  eturns what woul
fc50: 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74  d be the allocat
fc60: 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20  ed size of.** a 
fc70: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
fc80: 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63  n given a partic
fc90: 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73  ular requested s
fca0: 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72  ize.  Most memor
fcb0: 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20  y.** allocators 
fcc0: 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20  round up memory 
fcd0: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c  allocations at l
fce0: 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74  east to the next
fcf0: 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20   multiple.** of 
fd00: 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74  8.  Some allocat
fd10: 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20  ors round up to 
fd20: 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c  a larger multipl
fd30: 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20  e or to a power 
fd40: 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d  of 2..** Every m
fd50: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
fd60: 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20   request coming 
fd70: 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69  in through [sqli
fd80: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  te3_malloc()].**
fd90: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
fda0: 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61  lloc()] first ca
fdb0: 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49  lls xRoundup.  I
fdc0: 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72  f xRoundup retur
fdd0: 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63  ns 0, .** that c
fde0: 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73  auses the corres
fdf0: 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61  ponding memory a
fe00: 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69  llocation to fai
fe10: 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e  l..**.** The xIn
fe20: 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61  it method initia
fe30: 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  lizes the memory
fe40: 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f   allocator.  (Fo
fe50: 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74  r example,.** it
fe60: 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20   might allocate 
fe70: 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65  any require mute
fe80: 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a  xes or initializ
fe90: 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a  e internal data.
fea0: 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20  ** structures.  
feb0: 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  The xShutdown me
fec0: 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20  thod is invoked 
fed0: 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a  (indirectly) by.
fee0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
fef0: 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75  down()] and shou
ff00: 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e  ld deallocate an
ff10: 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75  y resources acqu
ff20: 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74  ired.** by xInit
ff30: 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20  .  The pAppData 
ff40: 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20  pointer is used 
ff50: 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
ff60: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69  meter to.** xIni
ff70: 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e  t and xShutdown.
ff80: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f  .**.** SQLite ho
ff90: 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
ffa0: 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53  MUTEX_STATIC_MAS
ffb0: 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20  TER] mutex when 
ffc0: 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68  it invokes.** th
ffd0: 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20  e xInit method, 
ffe0: 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  so the xInit met
fff0: 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  hod need not be 
10000 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
10010 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  .** xShutdown me
10020 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c  thod is only cal
10030 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  led from [sqlite
10040 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f  3_shutdown()] so
10050 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20   it does.** not 
10060 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61  need to be threa
10070 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46  dsafe either.  F
10080 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74  or all other met
10090 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  hods, SQLite.** 
100a0 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
100b0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
100c0 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e  EM] mutex as lon
100d0 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  g as the.** [SQL
100e0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
100f0 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74  ATUS] configurat
10100 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75  ion option is tu
10110 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a  rned on (which.*
10120 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75  * it is by defau
10130 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d  lt) and so the m
10140 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d  ethods are autom
10150 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69  atically seriali
10160 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  zed..** However,
10170 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   if [SQLITE_CONF
10180 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73  IG_MEMSTATUS] is
10190 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20   disabled, then 
101a0 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74  the other.** met
101b0 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72  hods must be thr
101c0 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20  eadsafe or else 
101d0 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61  make their own a
101e0 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a  rrangements for.
101f0 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e  ** serialization
10200 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ..**.** SQLite w
10210 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  ill never invoke
10220 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68   xInit() more th
10230 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20  an once without 
10240 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a  an intervening.*
10250 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64  * call to xShutd
10260 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65  own()..*/.typede
10270 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
10280 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c  _mem_methods sql
10290 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
102a0 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
102b0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  _mem_methods {. 
102c0 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63   void *(*xMalloc
102d0 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
102e0 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  /* Memory alloca
102f0 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  tion function */
10300 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29  .  void (*xFree)
10310 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
10320 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f    /* Free a prio
10330 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  r allocation */.
10340 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c    void *(*xReall
10350 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20  oc)(void*,int); 
10360 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c   /* Resize an al
10370 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
10380 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a  t (*xSize)(void*
10390 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
103a0 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20  Return the size 
103b0 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  of an allocation
103c0 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75   */.  int (*xRou
103d0 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20  ndup)(int);     
103e0 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70       /* Round up
103f0 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f   request size to
10400 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
10410 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69   */.  int (*xIni
10420 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  t)(void*);      
10430 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69       /* Initiali
10440 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
10450 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
10460 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76  d (*xShutdown)(v
10470 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44  oid*);      /* D
10480 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20  einitialize the 
10490 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
104a0 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
104b0 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20  Data;           
104c0 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74       /* Argument
104d0 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20   to xInit() and 
104e0 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d  xShutdown() */.}
104f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10500 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  F: Configuration
10510 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57   Options.** KEYW
10520 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61  ORDS: {configura
10530 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a  tion option}.**.
10540 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
10550 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
10560 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
10570 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10580 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
10590 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
105a0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
105b0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
105c0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
105d0 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
105e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
105f0 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
10600 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
10610 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
10620 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
10630 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
10640 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
10650 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
10660 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
10670 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
10680 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
10690 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  te3_config()] to
106a0 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
106b0 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
106c0 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ed.  The [sqlite
106d0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
106e0 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
106f0 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
10700 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
10710 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
10720 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
10730 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10740 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
10750 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
10760 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
10770 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c  SINGLETHREAD]] <
10780 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
10790 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64  _SINGLETHREAD</d
107a0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
107b0 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
107c0 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
107d0 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
107e0 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
107f0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
10800 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49  ingle-thread.  I
10810 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
10820 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c  t disables.** al
10830 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70  l mutexing and p
10840 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20  uts SQLite into 
10850 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20  a mode where it 
10860 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
10870 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20  .** by a single 
10880 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51  thread.   ^If SQ
10890 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
108a0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
108b0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
108c0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
108d0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
108e0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
108f0 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
10900 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20  sible to change 
10910 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
10920 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65  ode] from its de
10930 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f  fault.** value o
10940 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  f Single-thread 
10950 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f  and so [sqlite3_
10960 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
10970 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  eturn .** [SQLIT
10980 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
10990 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
109a0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
109b0 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67  THREAD.** config
109c0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
109d0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
109e0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
109f0 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
10a00 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
10a10 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
10a20 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
10a30 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
10a40 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
10a50 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
10a60 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
10a70 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68  ode] to Multi-th
10a80 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
10a90 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
10aa0 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f  es.** mutexing o
10ab0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
10ac0 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
10ad0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
10ae0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65   objects..** The
10af0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
10b00 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
10b10 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65  serializing acce
10b20 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61  ss to.** [databa
10b30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
10b40 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
10b50 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20  atements].  But 
10b60 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a  other mutexes.**
10b70 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20   are enabled so 
10b80 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
10b90 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20   be safe to use 
10ba0 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  in a multi-threa
10bb0 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65  ded.** environme
10bc0 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f  nt as long as no
10bd0 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74   two threads att
10be0 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20  empt to use the 
10bf0 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  same.** [databas
10c00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
10c10 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20   the same time. 
10c20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
10c30 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
10c40 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
10c50 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
10c60 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
10c70 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
10c80 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
10c90 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
10ca0 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68  set the Multi-th
10cb0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
10cc0 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
10cd0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
10ce0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
10cf0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
10d00 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
10d10 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
10d20 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69  ULTITHREAD confi
10d30 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
10d40 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
10d50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
10d60 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c  ALIZED]] <dt>SQL
10d70 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
10d80 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  LIZED</dt>.** <d
10d90 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
10da0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
10db0 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
10dc0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
10dd0 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
10de0 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65  de] to Serialize
10df0 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  d. In other word
10e00 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65  s, this option e
10e10 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  nables.** all mu
10e20 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  texes including 
10e30 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a  the recursive.**
10e40 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74   mutexes on [dat
10e50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10e60 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
10e70 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
10e80 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d  ts..** In this m
10e90 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68  ode (which is th
10ea0 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53  e default when S
10eb0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
10ec0 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54  d with.** [SQLIT
10ed0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29  E_THREADSAFE=1])
10ee0 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
10ef0 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20  ary will itself 
10f00 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73  serialize access
10f10 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65  .** to [database
10f20 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
10f30 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
10f40 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20  ements] so that 
10f50 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  the.** applicati
10f60 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73  on is free to us
10f70 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  e the same [data
10f80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10f90 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20   or the.** same 
10fa0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
10fb0 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e  ent] in differen
10fc0 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  t threads at the
10fd0 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e   same time..** ^
10fe0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
10ff0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
11000 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
11010 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
11020 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
11030 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
11040 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
11050 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
11060 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64  t the Serialized
11070 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11080 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
11090 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
110a0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
110b0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
110c0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
110d0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
110e0 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74  LIZED configurat
110f0 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
11100 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11110 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20  CONFIG_MALLOC]] 
11120 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11130 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  G_MALLOC</dt>.**
11140 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
11150 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
11160 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
11170 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
11180 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
11190 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
111a0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
111b0 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
111c0 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
111d0 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
111e0 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
111f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
11200 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
11210 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
11220 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
11230 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
11240 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
11250 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  )^ ^SQLite makes
11260 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76  .** its own priv
11270 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
11280 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
11290 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
112a0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a  ods] structure.*
112b0 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71  * before the [sq
112c0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
112d0 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64  call returns.</d
112e0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
112f0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
11300 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
11310 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
11320 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
11330 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
11340 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
11350 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
11360 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
11370 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
11380 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
11390 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
113a0 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
113b0 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  em_methods].** s
113c0 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
113d0 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
113e0 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65  ently defined me
113f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11400 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
11410 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
11420 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
11430 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
11440 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11450 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
11460 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74  h a wrapper that
11470 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d   simulations mem
11480 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
11490 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61  ailure or.** tra
114a0 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  cks memory usage
114b0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c  , for example. <
114c0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
114d0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
114e0 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATUS]] <dt>SQLIT
114f0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
11500 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  US</dt>.** <dd> 
11510 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
11520 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65  es single argume
11530 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20  nt of type int, 
11540 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
11550 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68   .** boolean, wh
11560 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ich enables or d
11570 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c  isables the coll
11580 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79  ection of memory
11590 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20   allocation .** 
115a0 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68  statistics. ^(Wh
115b0 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  en memory alloca
115c0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
115d0 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68  are disabled, th
115e0 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  e .** following 
115f0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
11600 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65  s become non-ope
11610 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c  rational:.**   <
11620 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ul>.**   <li> [s
11630 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
11640 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ed()].**   <li> 
11650 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
11660 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20  highwater()].** 
11670 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
11680 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
11690 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  4()].**   <li> [
116a0 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29  sqlite3_status()
116b0 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a  ].**   </ul>)^.*
116c0 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  * ^Memory alloca
116d0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
116e0 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
116f0 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51  efault unless SQ
11700 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  Lite is.** compi
11710 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
11720 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54  _DEFAULT_MEMSTAT
11730 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63  US]=0 in which c
11740 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ase memory.** al
11750 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
11760 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ics are disabled
11770 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20   by default..** 
11780 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
11790 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
117a0 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TCH]] <dt>SQLITE
117b0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c  _CONFIG_SCRATCH<
117c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
117d0 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
117e0 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
117f0 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
11800 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
11810 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65  or.** scratch me
11820 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72 65  mory.  There are
11830 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
11840 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20  :  A pointer an 
11850 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65  8-byte.** aligne
11860 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  d memory buffer 
11870 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73  from which the s
11880 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
11890 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72  ns will be.** dr
118a0 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  awn, the size of
118b0 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61 6c   each scratch al
118c0 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a  location (sz),.*
118d0 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75  * and the maximu
118e0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61  m number of scra
118f0 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  tch allocations 
11900 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20  (N).  The sz.** 
11910 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
11920 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31   a multiple of 1
11930 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  6..** The first 
11940 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
11950 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
11960 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
11970 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20  buffer.** of at 
11980 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
11990 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
119a0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
119b0 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f  no more than two
119c0 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73   scratch buffers
119d0 20 70 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f   per thread.  So
119e0 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20  .** N should be 
119f0 73 65 74 20 74 6f 20 74 77 69 63 65 20 74 68 65  set to twice the
11a00 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75   expected maximu
11a10 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65  m number of thre
11a20 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ads..** ^SQLite 
11a30 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69  will never requi
11a40 72 65 20 61 20 73 63 72 61 74 63 68 20 62 75 66  re a scratch buf
11a50 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65  fer that is more
11a60 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73   than 6.** times
11a70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
11a80 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c  ge size. ^If SQL
11a90 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20  ite needs needs 
11aa0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63  additional.** sc
11ab0 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79  ratch memory bey
11ac0 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
11ad0 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e  ided by this con
11ae0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11af0 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c  n, then .** [sql
11b00 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77  ite3_malloc()] w
11b10 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f  ill be used to o
11b20 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  btain the memory
11b30 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a   needed.</dd>.**
11b40 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
11b50 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20  FIG_PAGECACHE]] 
11b60 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11b70 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e  G_PAGECACHE</dt>
11b80 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
11b90 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
11ba0 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
11bb0 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
11bc0 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
11bd0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  * the database p
11be0 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74  age cache with t
11bf0 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 20  he default page 
11c00 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
11c10 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20  tion.  .** This 
11c20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68  configuration sh
11c30 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
11c40 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
11c50 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a  on-define page.*
11c60 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
11c70 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64  tation is loaded
11c80 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54   using the SQLIT
11c90 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
11ca0 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72   option..** Ther
11cb0 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
11cc0 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
11cd0 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20  tion: A pointer 
11ce0 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  to 8-byte aligne
11cf0 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65  d.** memory, the
11d00 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61   size of each pa
11d10 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20  ge buffer (sz), 
11d20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
11d30 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20  f pages (N)..** 
11d40 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20  The sz argument 
11d50 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69  should be the si
11d60 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ze of the larges
11d70 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a  t database page.
11d80 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74  ** (a power of t
11d90 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
11da0 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73 20 61  nd 32768) plus a
11db0 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f   little extra fo
11dc0 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68  r each.** page h
11dd0 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67  eader.  ^The pag
11de0 65 20 68 65 61 64 65 72 20 73 69 7a 65 20 69 73  e header size is
11df0 20 32 30 20 74 6f 20 34 30 20 62 79 74 65 73 20   20 to 40 bytes 
11e00 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20  depending on.** 
11e10 74 68 65 20 68 6f 73 74 20 61 72 63 68 69 74 65  the host archite
11e20 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68  cture.  ^It is h
11e30 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66  armless, apart f
11e40 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d  rom the wasted m
11e50 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b  emory,.** to mak
11e60 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f  e sz a little to
11e70 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69  o large.  The fi
11e80 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  rst.** argument 
11e90 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20  should point to 
11ea0 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66  an allocation of
11eb0 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
11ec0 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a  ytes of memory..
11ed0 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
11ee0 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  use the memory p
11ef0 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66  rovided by the f
11f00 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
11f10 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20   satisfy its.** 
11f20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72  memory needs for
11f30 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67   the first N pag
11f40 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20  es that it adds 
11f50 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61  to cache.  ^If a
11f60 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67  dditional.** pag
11f70 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69  e cache memory i
11f80 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20  s needed beyond 
11f90 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
11fa0 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c   by this option,
11fb0 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
11fc0 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  goes to [sqlite3
11fd0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74  _malloc()] for t
11fe0 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74  he additional st
11ff0 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20  orage space..** 
12000 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74  The pointer in t
12010 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
12020 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69  t must.** be ali
12030 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
12040 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75  e boundary or su
12050 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
12060 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  r of SQLite.** w
12070 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
12080 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
12090 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
120a0 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  P]] <dt>SQLITE_C
120b0 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a  ONFIG_HEAP</dt>.
120c0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
120d0 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
120e0 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
120f0 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
12100 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f  e will use.** fo
12110 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e  r all of its dyn
12120 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  amic memory allo
12130 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79  cation needs bey
12140 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64  ond those provid
12150 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51  ed.** for by [SQ
12160 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
12170 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  TCH] and [SQLITE
12180 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
12190 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  E]..** There are
121a0 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
121b0 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  : An 8-byte alig
121c0 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ned pointer to t
121d0 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68  he memory,.** th
121e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
121f0 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  s in the memory 
12200 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20  buffer, and the 
12210 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
12220 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  on size..** ^If 
12230 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  the first pointe
12240 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
12250 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20  inter) is NULL, 
12260 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65  then SQLite reve
12270 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20  rts.** to using 
12280 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  its default memo
12290 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68  ry allocator (th
122a0 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
122b0 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ) implementation
122c0 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e  ),.** undoing an
122d0 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69  y prior invocati
122e0 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f  on of [SQLITE_CO
122f0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e  NFIG_MALLOC].  ^
12300 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  If the.** memory
12310 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
12320 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20  NULL and either 
12330 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
12340 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53  EMSYS3] or.** [S
12350 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
12360 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65  SYS5] are define
12370 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65  d, then the alte
12380 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a  rnative memory.*
12390 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65  * allocator is e
123a0 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65  ngaged to handle
123b0 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20   all of SQLites 
123c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
123d0 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20  n needs..** The 
123e0 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
123f0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
12400 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  r) must be align
12410 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  ed to an 8-byte.
12420 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73  ** boundary or s
12430 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
12440 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c  or of SQLite wil
12450 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a  l be undefined..
12460 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61  ** The minimum a
12470 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69  llocation size i
12480 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31  s capped at 2**1
12490 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61  2. Reasonable va
124a0 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20  lues.** for the 
124b0 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
124c0 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35  on size are 2**5
124d0 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f   through 2**8.</
124e0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
124f0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d  TE_CONFIG_MUTEX]
12500 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12510 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  FIG_MUTEX</dt>.*
12520 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
12530 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
12540 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
12550 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
12560 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
12570 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
12580 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
12590 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
125a0 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
125b0 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
125c0 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74  ve low-level mut
125d0 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  ex routines to b
125e0 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a  e used in place.
125f0 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75  ** the mutex rou
12600 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
12610 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c   SQLite.)^  ^SQL
12620 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
12630 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65   of the.** conte
12640 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
12650 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
12660 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f  ] structure befo
12670 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a  re the call to.*
12680 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
12690 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49  g()] returns. ^I
126a0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
126b0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
126c0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
126d0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
126e0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
126f0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
12700 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
12710 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
12720 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
12730 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
12740 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
12750 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
12760 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
12770 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
12780 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
12790 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
127a0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
127b0 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
127c0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
127d0 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c  FIG_GETMUTEX]] <
127e0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
127f0 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  _GETMUTEX</dt>.*
12800 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
12810 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
12820 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
12830 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
12840 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
12850 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
12860 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
12870 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
12880 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  .** [sqlite3_mut
12890 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  ex_methods].** s
128a0 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
128b0 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
128c0 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75  ently defined mu
128d0 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  tex routines.)^.
128e0 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
128f0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
12900 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
12910 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74  lt mutex allocat
12920 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
12930 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75  with a wrapper u
12940 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74  sed to track mut
12950 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72  ex usage for per
12960 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66  formance.** prof
12970 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67  iling or testing
12980 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20  , for example.  
12990 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
129a0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
129b0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
129c0 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
129d0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
129e0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
129f0 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
12a00 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
12a10 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
12a20 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
12a30 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
12a40 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
12a50 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
12a60 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
12a70 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69  G_GETMUTEX confi
12a80 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
12a90 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
12aa0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
12ab0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
12ac0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
12ad0 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  IDE]] <dt>SQLITE
12ae0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
12af0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
12b00 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
12b10 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
12b20 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
12b30 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d  the default.** m
12b40 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12b50 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69   for the lookasi
12b60 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
12b70 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b  tor on each.** [
12b80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12b90 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ion].  The first
12ba0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
12bb0 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
12bc0 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
12bd0 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73  r slot and the s
12be0 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d  econd is the num
12bf0 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20  ber of.** slots 
12c00 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63  allocated to eac
12c10 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
12c20 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73  ction.)^  ^(This
12c30 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
12c40 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f  .** <i>default</
12c50 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a  i> lookaside siz
12c60 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44  e. The [SQLITE_D
12c70 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
12c80 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73  E].** verb to [s
12c90 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
12ca0 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20  ()] can be used 
12cb0 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f  to change the lo
12cc0 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69  okaside.** confi
12cd0 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69  guration on indi
12ce0 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f  vidual connectio
12cf0 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ns.)^ </dd>.**.*
12d00 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12d10 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  G_PCACHE2]] <dt>
12d20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
12d30 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
12d40 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
12d50 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
12d60 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
12d70 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  s a pointer to.*
12d80 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  * an [sqlite3_pc
12d90 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
12da0 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
12db0 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68  ect specifies th
12dc0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74  e interface.** t
12dd0 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20  o a custom page 
12de0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
12df0 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65  tion.)^  ^SQLite
12e00 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
12e10 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61   the.** object a
12e20 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70  nd uses it for p
12e30 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
12e40 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64   allocations.</d
12e50 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12e60 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
12e70 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
12e80 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
12e90 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  E2</dt>.** <dd> 
12ea0 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
12eb0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
12ec0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
12ed0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
12ee0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  * [sqlite3_pcach
12ef0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
12f00 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
12f10 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  es of the curren
12f20 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  t.** page cache 
12f30 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
12f40 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
12f50 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
12f60 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
12f70 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OG]] <dt>SQLITE_
12f80 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a  CONFIG_LOG</dt>.
12f90 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
12fa0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f  ITE_CONFIG_LOG o
12fb0 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
12fc0 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69  arguments: a poi
12fd0 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e  nter to a.** fun
12fe0 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c  ction with a cal
12ff0 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76  l signature of v
13000 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  oid(*)(void*,int
13010 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a  ,const char*), .
13020 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72  ** and a pointer
13030 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68   to void. ^If th
13040 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
13050 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  er is not NULL, 
13060 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64  it is.** invoked
13070 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67   by [sqlite3_log
13080 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65  ()] to process e
13090 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e  ach logging even
130a0 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66  t.  ^If the.** f
130b0 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
130c0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71  is NULL, the [sq
130d0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74  lite3_log()] int
130e0 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61  erface becomes a
130f0 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20   no-op..** ^The 
13100 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61  void pointer tha
13110 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  t is the second 
13120 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49  argument to SQLI
13130 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73  TE_CONFIG_LOG is
13140 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75  .** passed throu
13150 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
13160 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
13170 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
13180 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
13190 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72  unction whenever
131a0 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69   that function i
131b0 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65  s invoked.  ^The
131c0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
131d0 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67  r to.** the logg
131e0 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  er function is a
131f0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72   copy of the fir
13200 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
13210 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
13220 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  g.** [sqlite3_lo
13230 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73  g()] call and is
13240 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20   intended to be 
13250 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  a [result code] 
13260 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64  or an.** [extend
13270 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e  ed result code].
13280 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72    ^The third par
13290 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f  ameter passed to
132a0 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a   the logger is.*
132b0 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66  * log message af
132c0 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76  ter formatting v
132d0 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ia [sqlite3_snpr
132e0 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  intf()]..** The 
132f0 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69  SQLite logging i
13300 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
13310 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c  reentrant; the l
13320 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a  ogger function.*
13330 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68  * supplied by th
13340 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
13350 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e  st not invoke an
13360 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
13370 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74  ce..** In a mult
13380 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69  i-threaded appli
13390 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c  cation, the appl
133a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
133b0 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
133c0 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  on must be threa
133d0 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  dsafe. </dd>.**.
133e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
133f0 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c  IG_URI]] <dt>SQL
13400 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a  ITE_CONFIG_URI.*
13410 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f 70 74 69  * <dd> This opti
13420 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
13430 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
13440 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a  pe int. If non-z
13450 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49  ero, then.** URI
13460 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
13470 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49  bally enabled. I
13480 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
13490 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52  is zero, then UR
134a0 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73  I handling.** is
134b0 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c   globally disabl
134c0 65 64 2e 20 49 66 20 55 52 49 20 68 61 6e 64 6c  ed. If URI handl
134d0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
134e0 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c  enabled, all fil
134f0 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64  enames.** passed
13500 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
13510 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
13520 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  pen_v2()], [sqli
13530 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72  te3_open16()] or
13540 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73  .** specified as
13550 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48   part of [ATTACH
13560 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69  ] commands are i
13570 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
13580 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a  Is, regardless.*
13590 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  * of whether or 
135a0 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  not the [SQLITE_
135b0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
135c0 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64  s set when the d
135d0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
135e0 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
135f0 20 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c   If it is global
13600 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c  ly disabled, fil
13610 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e  enames are.** on
13620 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ly interpreted a
13630 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51  s URIs if the SQ
13640 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c  LITE_OPEN_URI fl
13650 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
13660 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
13670 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
13680 6e 65 64 2e 20 42 79 20 64 65 66 61 75 6c 74 2c  ned. By default,
13690 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
136a0 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73   globally.** dis
136b0 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75  abled. The defau
136c0 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20  lt value may be 
136d0 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69  changed by compi
136e0 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a  ling with the.**
136f0 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
13700 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  ] symbol defined
13710 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
13720 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
13730 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64  _INDEX_SCAN]] <d
13740 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13750 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
13760 43 41 4e 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73  CAN.** <dd> This
13770 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
13780 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 20 61  single integer a
13790 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
137a0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 0a   interpreted as.
137b0 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20  ** a boolean in 
137c0 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20  order to enable 
137d0 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 75  or disable the u
137e0 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69  se of covering i
137f0 6e 64 69 63 65 73 20 66 6f 72 0a 2a 2a 20 66 75  ndices for.** fu
13800 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69  ll table scans i
13810 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 69  n the query opti
13820 6d 69 7a 65 72 2e 20 20 54 68 65 20 64 65 66 61  mizer.  The defa
13830 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20 64  ult setting is d
13840 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20  etermined.** by 
13850 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f  the [SQLITE_ALLO
13860 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  W_COVERING_INDEX
13870 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74  _SCAN] compile-t
13880 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69  ime option, or i
13890 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61  s "on".** if tha
138a0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
138b0 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ption is omitted
138c0 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79  ..** The ability
138d0 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20   to disable the 
138e0 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20  use of covering 
138f0 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c  indices for full
13900 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20   table scans.** 
13910 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20  is because some 
13920 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65  incorrectly code
13930 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61  d legacy applica
13940 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66  tions might malf
13950 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 61 6c 66 75  unction.** malfu
13960 6e 63 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20  nction when the 
13970 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20  optimization is 
13980 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64  enabled.  Provid
13990 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20  ing the ability 
139a0 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68  to.** disable th
139b0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61  e optimization a
139c0 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c  llows the older,
139d0 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69   buggy applicati
139e0 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a  on code to work.
139f0 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  ** without chang
13a00 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65  e even with newe
13a10 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
13a20 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  Lite..**.** [[SQ
13a30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
13a40 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  HE]] [[SQLITE_CO
13a50 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d  NFIG_GETPCACHE]]
13a60 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
13a70 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64  ONFIG_PCACHE and
13a80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
13a90 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e  ETPCACHE.** <dd>
13aa0 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61   These options a
13ab0 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20  re obsolete and 
13ac0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
13ad0 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a  ed by new code..
13ae0 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61  ** They are reta
13af0 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  ined for backwar
13b00 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
13b10 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d   but are now no-
13b20 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  ops..** </dl>.**
13b30 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13b40 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20  FIG_SQLLOG]].** 
13b50 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13b60 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e  G_SQLLOG.** <dd>
13b70 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f  This option is o
13b80 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
13b90 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69   sqlite is compi
13ba0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
13bb0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51  SQLITE_ENABLE_SQ
13bc0 4c 4c 4f 47 20 70 72 65 2d 70 72 6f 63 65 73 73  LLOG pre-process
13bd0 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64  or macro defined
13be0 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  . The first argu
13bf0 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62  ment should.** b
13c00 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
13c10 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
13c20 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  e void(*)(void*,
13c30 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63  sqlite3*,const c
13c40 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54  har*, int)..** T
13c50 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64  he second should
13c60 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69   be of type (voi
13c70 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63  d*). The callbac
13c80 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  k is invoked by 
13c90 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69  the library.** i
13ca0 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65  n three separate
13cb0 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20   circumstances, 
13cc0 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
13cd0 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
13ce0 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  s the.** fourth 
13cf0 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68  parameter. If th
13d00 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
13d10 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68  er is 0, then th
13d20 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
13d30 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20  ction.** passed 
13d40 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
13d50 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20  gument has just 
13d60 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65  been opened. The
13d70 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a   third argument.
13d80 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62  ** points to a b
13d90 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67  uffer containing
13da0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
13db0 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
13dc0 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66  ile. If the.** f
13dd0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
13de0 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53  is 1, then the S
13df0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
13e00 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  t the third para
13e10 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20  meter.** points 
13e20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  to has just been
13e30 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69   executed. Or, i
13e40 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
13e50 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65  ameter is 2, the
13e60 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74  n.** the connect
13e70 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64  ion being passed
13e80 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
13e90 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e  arameter is bein
13ea0 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a  g closed. The.**
13eb0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
13ec0 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20   is passed NULL 
13ed0 49 6e 20 74 68 69 73 20 63 61 73 65 2e 0a 2a 2a  In this case..**
13ee0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
13ef0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13f00 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20  SINGLETHREAD  1 
13f10 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
13f20 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
13f30 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32  _MULTITHREAD   2
13f40 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
13f50 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
13f60 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20  G_SERIALIZED    
13f70 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  3  /* nil */.#de
13f80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
13f90 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  IG_MALLOC       
13fa0 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   4  /* sqlite3_m
13fb0 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
13fc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
13fd0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20  NFIG_GETMALLOC  
13fe0 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33     5  /* sqlite3
13ff0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
14000 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14010 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20  CONFIG_SCRATCH  
14020 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a       6  /* void*
14030 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
14040 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14050 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
14060 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69  HE     7  /* voi
14070 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
14080 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
14090 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
140a0 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76           8  /* v
140b0 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  oid*, int nByte,
140c0 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66   int min */.#def
140d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
140e0 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20  G_MEMSTATUS     
140f0 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f  9  /* boolean */
14100 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14110 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20  CONFIG_MUTEX    
14120 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74      10  /* sqlit
14130 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
14140 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
14150 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
14160 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73  TEX     11  /* s
14170 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
14180 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76  hods* */./* prev
14190 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f  iously SQLITE_CO
141a0 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20  NFIG_CHUNKALLOC 
141b0 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20  12 which is now 
141c0 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66  unused. */ .#def
141d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
141e0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
141f0 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  3  /* int int */
14200 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14210 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20  CONFIG_PCACHE   
14220 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70      14  /* no-op
14230 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14240 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
14250 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f  CHE    15  /* no
14260 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
14270 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
14280 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a            16  /*
14290 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f   xFunc, void* */
142a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
142b0 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20  CONFIG_URI      
142c0 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a      17  /* int *
142d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
142e0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
142f0 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69       18  /* sqli
14300 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
14310 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ds2* */.#define 
14320 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14330 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f  TPCACHE2   19  /
14340 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
14350 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
14360 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14370 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
14380 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69  EX_SCAN 20  /* i
14390 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
143a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
143b0 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20  OG       21  /* 
143c0 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a  xSqllog, void* *
143d0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
143e0 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
143f0 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61  ection Configura
14400 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a  tion Options.**.
14410 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
14420 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
14430 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
14440 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
14450 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
14460 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
14470 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
14480 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
14490 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
144a0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
144b0 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
144c0 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
144d0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
144e0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
144f0 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
14500 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
14510 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
14520 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
14530 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
14540 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
14550 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
14560 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
14570 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
14580 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
14590 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65  ll worked.  ^The
145a0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
145b0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
145c0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
145d0 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
145e0 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
145f0 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
14600 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
14610 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
14620 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
14630 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
14640 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
14650 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
14660 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
14670 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61  on takes three a
14680 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
14690 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
146a0 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b  ne the .** [look
146b0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
146c0 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72  ocator] configur
146d0 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64  ation for the [d
146e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
146f0 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  on]..** ^The fir
14700 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65  st argument (the
14710 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
14720 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
14730 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a  config()] is a.*
14740 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  * pointer to a m
14750 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
14760 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
14770 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68  e memory..** ^Th
14780 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
14790 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54   after the SQLIT
147a0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
147b0 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79  SIDE verb.** may
147c0 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63   be NULL in whic
147d0 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69  h case SQLite wi
147e0 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a  ll allocate the.
147f0 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ** lookaside buf
14800 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67  fer itself using
14810 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
14820 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ()]. ^The second
14830 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
14840 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
14850 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
14860 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68  r slot.  ^The th
14870 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
14880 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
14890 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a   slots.  The siz
148a0 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  e of the buffer 
148b0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
148c0 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72  ument must be gr
148d0 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72  eater than.** or
148e0 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72   equal to the pr
148f0 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63  oduct of the sec
14900 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72  ond and third ar
14910 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75  guments.  The bu
14920 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20  ffer.** must be 
14930 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
14940 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20  byte boundary.  
14950 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61  ^If the second a
14960 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51  rgument to.** SQ
14970 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
14980 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61  OKASIDE is not a
14990 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20   multiple of 8, 
149a0 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79  it is internally
149b0 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e  .** rounded down
149c0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61   to the next sma
149d0 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ller multiple of
149e0 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61   8.  ^(The looka
149f0 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63  side memory.** c
14a00 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
14a10 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
14a20 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20  ection can only 
14a30 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20  be changed when 
14a40 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  that.** connecti
14a50 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  on is not curren
14a60 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73  tly using lookas
14a70 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69  ide memory, or i
14a80 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a  n other words.**
14a90 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65   when the "curre
14aa0 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e  nt value" return
14ab0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
14ac0 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b  3_db_status](D,[
14ad0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14ae0 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73  OKASIDE],...) is
14af0 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74   zero..** Any at
14b00 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20  tempt to change 
14b10 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
14b20 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69  mory configurati
14b30 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64  on when lookasid
14b40 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69  e.** memory is i
14b50 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65  n use leaves the
14b60 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
14b70 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74  nchanged and ret
14b80 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  urns .** [SQLITE
14b90 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  _BUSY].)^</dd>.*
14ba0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
14bb0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
14bc0 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FKEY</dt>.** <dd
14bd0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
14be0 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
14bf0 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
14c00 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a  enforcement of.*
14c10 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  * [foreign key c
14c20 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68  onstraints].  Th
14c30 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
14c40 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
14c50 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
14c60 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
14c70 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
14c80 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
14c90 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
14ca0 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
14cb0 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72   enable FK enfor
14cc0 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69  cement or negati
14cd0 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65  ve to leave FK e
14ce0 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e  nforcement.** un
14cf0 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65  changed.  The se
14d00 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
14d10 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
14d20 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
14d30 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
14d40 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
14d50 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b  icate whether FK
14d60 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20   enforcement is 
14d70 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c  off or on.** fol
14d80 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
14d90 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
14da0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
14db0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
14dc0 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
14dd0 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  the FK enforceme
14de0 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  nt setting is no
14df0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
14e00 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
14e10 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
14e20 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c  _ENABLE_TRIGGER<
14e30 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
14e40 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
14e50 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
14e60 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54  isable [CREATE T
14e70 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
14e80 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  s]..** There sho
14e90 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
14ea0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
14eb0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
14ec0 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
14ed0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
14ee0 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67  to disable trigg
14ef0 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ers,.** positive
14f00 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67   to enable trigg
14f10 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ers or negative 
14f20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
14f30 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
14f40 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
14f50 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
14f60 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
14f70 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
14f80 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
14f90 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
14fa0 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20  hether triggers 
14fb0 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20  are disabled or 
14fc0 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  enabled.** follo
14fd0 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
14fe0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
14ff0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
15000 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
15010 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
15020 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e  e trigger settin
15030 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
15040 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
15050 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
15060 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
15070 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
15080 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f       1001  /* vo
15090 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23  id* int int */.#
150a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
150b0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
150c0 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20  EY     1002  /* 
150d0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
150e0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
150f0 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
15100 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74  ER  1003  /* int
15110 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a   int* */.../*.**
15120 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
15130 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
15140 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
15150 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
15160 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
15170 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
15180 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
15190 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
151a0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
151b0 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
151c0 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
151d0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
151e0 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
151f0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
15200 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
15210 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
15220 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
15230 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
15240 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69  odes(sqlite3*, i
15250 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
15260 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74  * CAPI3REF: Last
15270 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a   Insert Rowid.**
15280 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20  .** ^Each entry 
15290 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62  in an SQLite tab
152a0 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  le has a unique 
152b0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a  64-bit signed.**
152c0 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c   integer key cal
152d0 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c  led the [ROWID |
152e0 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20   "rowid"]. ^The 
152f0 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
15300 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
15310 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
15320 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
15330 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
15340 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
15350 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
15360 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
15370 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
15380 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49  ared columns. ^I
15390 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
153a0 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
153b0 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
153c0 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
153d0 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
153e0 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
153f0 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
15400 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
15410 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72  e returns the [r
15420 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73  owid] of the mos
15430 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63  t recent.** succ
15440 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
15450 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
15460 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61  e from the [data
15470 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
15480 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
15490 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20   argument.  ^As 
154a0 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
154b0 6e 20 33 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f  n 3.7.7, this ro
154c0 75 74 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64  utines.** record
154d0 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72  s the last inser
154e0 74 20 72 6f 77 69 64 20 6f 66 20 62 6f 74 68 20  t rowid of both 
154f0 6f 72 64 69 6e 61 72 79 20 74 61 62 6c 65 73 20  ordinary tables 
15500 61 6e 64 20 5b 76 69 72 74 75 61 6c 20 74 61 62  and [virtual tab
15510 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20  les]..** ^If no 
15520 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
15530 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65  RT]s.** have eve
15540 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68  r occurred on th
15550 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  at database conn
15560 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20  ection, zero is 
15570 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
15580 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
15590 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
155a0 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68   trigger or with
155b0 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  in a [virtual ta
155c0 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20  ble].** method, 
155d0 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
155e0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68  e will return th
155f0 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
15600 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77   inserted.** row
15610 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
15620 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
15630 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  al table method 
15640 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42  is running..** B
15650 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67  ut once the trig
15660 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74  ger or virtual t
15670 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73  able method ends
15680 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
15690 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73  rned .** by this
156a0 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73   routine reverts
156b0 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20   to what it was 
156c0 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
156d0 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a  er or virtual.**
156e0 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65   table method be
156f0 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  gan.)^.**.** ^An
15700 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66   [INSERT] that f
15710 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
15720 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
15730 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
15740 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
15750 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  T] and does not 
15760 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
15770 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
15780 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e  s.** routine.  ^
15790 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46  Thus INSERT OR F
157a0 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49  AIL, INSERT OR I
157b0 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52  GNORE, INSERT OR
157c0 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e   ROLLBACK,.** an
157d0 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52  d INSERT OR ABOR
157e0 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65  T make no change
157f0 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20  s to the return 
15800 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a  value of this.**
15810 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68   routine when th
15820 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61  eir insertion fa
15830 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53  ils.  ^(When INS
15840 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a  ERT OR REPLACE.*
15850 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63  * encounters a c
15860 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
15870 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74  ion, it does not
15880 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49   fail.  The.** I
15890 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20  NSERT continues 
158a0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66  to completion af
158b0 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77  ter deleting row
158c0 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a  s that caused.**
158d0 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
158e0 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52  problem so INSER
158f0 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c  T OR REPLACE wil
15900 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a  l always change.
15910 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ** the return va
15920 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  lue of this inte
15930 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  rface.)^.**.** ^
15940 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
15950 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
15960 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73  , an [INSERT] is
15970 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a   considered to.*
15980 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20  * be successful 
15990 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75  even if it is su
159a0 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65  bsequently rolle
159b0 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
159c0 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  is function is a
159d0 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c  ccessible to SQL
159e0 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20   statements via 
159f0 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73  the.** [last_ins
15a00 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20  ert_rowid() SQL 
15a10 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
15a20 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
15a30 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61  hread performs a
15a40 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e   new [INSERT] on
15a50 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74   the same.** dat
15a60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15a70 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69   while the [sqli
15a80 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
15a90 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63  rowid()].** func
15aa0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20  tion is running 
15ab0 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73  and thus changes
15ac0 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
15ad0 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65   [rowid],.** the
15ae0 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
15af0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
15b00 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
15b10 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72  id()] is.** unpr
15b20 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69  edictable and mi
15b30 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69  ght not equal ei
15b40 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20  ther the old or 
15b50 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20  the new.** last 
15b60 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a  insert [rowid]..
15b70 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
15b80 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
15b90 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
15ba0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
15bb0 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65  I3REF: Count The
15bc0 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
15bd0 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e  Modified.**.** ^
15be0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
15bf0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
15c00 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77   of database row
15c10 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e  s that were chan
15c20 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74  ged.** or insert
15c30 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79  ed or deleted by
15c40 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
15c50 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c  ly completed SQL
15c60 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e   statement.** on
15c70 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
15c80 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
15c90 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73  fied by the firs
15ca0 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  t parameter..** 
15cb0 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74  ^(Only changes t
15cc0 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79  hat are directly
15cd0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
15ce0 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44  e [INSERT], [UPD
15cf0 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c  ATE],.** or [DEL
15d00 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ETE] statement a
15d10 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78  re counted.  Aux
15d20 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63  iliary changes c
15d30 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67  aused by.** trig
15d40 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e  gers or [foreign
15d50 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72   key actions] ar
15d60 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e  e not counted.)^
15d70 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   Use the.** [sql
15d80 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
15d90 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74  es()] function t
15da0 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c  o find the total
15db0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67   number of chang
15dc0 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20  es.** including 
15dd0 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
15de0 79 20 74 72 69 67 67 65 72 73 20 61 6e 64 20 66  y triggers and f
15df0 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
15e00 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67  ns..**.** ^Chang
15e10 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61  es to a view tha
15e20 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20  t are simulated 
15e30 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f  by an [INSTEAD O
15e40 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72  F trigger].** ar
15e50 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20  e not counted.  
15e60 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20  Only real table 
15e70 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e  changes are coun
15e80 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22  ted..**.** ^(A "
15e90 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20 61  row change" is a
15ea0 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e   change to a sin
15eb0 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e  gle row of a sin
15ec0 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75  gle table.** cau
15ed0 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54  sed by an INSERT
15ee0 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44  , DELETE, or UPD
15ef0 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  ATE statement.  
15f00 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65  Rows that.** are
15f10 20 63 68 61 6e 67 65 64 20 61 73 20 73 69 64 65   changed as side
15f20 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50   effects of [REP
15f30 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
15f40 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20   resolution,.** 
15f50 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20  rollback, ABORT 
15f60 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f  processing, [DRO
15f70 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20  P TABLE], or by 
15f80 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63  any other.** mec
15f90 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63  hanisms do not c
15fa0 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72  ount as direct r
15fb0 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a  ow changes.)^.**
15fc0 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63  .** A "trigger c
15fd0 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f  ontext" is a sco
15fe0 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20  pe of execution 
15ff0 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a  that begins and.
16000 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65  ** ends with the
16010 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52   script of a [CR
16020 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
16030 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73  rigger]. .** Mos
16040 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  t SQL statements
16050 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65   are.** evaluate
16060 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79  d outside of any
16070 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 73 20   trigger.  This 
16080 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65  is the "top leve
16090 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f  l".** trigger co
160a0 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 72 69  ntext.  If a tri
160b0 67 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20  gger fires from 
160c0 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61  the top level, a
160d0 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20  .** new trigger 
160e0 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72  context is enter
160f0 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 61 74  ed for the durat
16100 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a  ion of that one.
16110 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75 62  ** trigger.  Sub
16120 74 72 69 67 67 65 72 73 20 63 72 65 61 74 65 20  triggers create 
16130 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20  subcontexts for 
16140 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a  their duration..
16150 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b  **.** ^Calling [
16160 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
16170 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  or [sqlite3_step
16180 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20  ()] recursively 
16190 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61  does.** not crea
161a0 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 72  te a new trigger
161b0 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
161c0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
161d0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
161e0 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20  r of direct row 
161f0 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a  changes in the.*
16200 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  * most recent IN
16210 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
16220 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
16230 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  t within the sam
16240 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e  e.** trigger con
16250 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75  text..**.** ^Thu
16260 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66  s, when called f
16270 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
16280 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  l, this function
16290 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
162a0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65  number of change
162b0 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
162c0 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
162d0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
162e0 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75  * that also occu
162f0 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20  rred at the top 
16300 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e  level.  ^(Within
16310 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74   the body of a t
16320 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73  rigger,.** the s
16330 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
16340 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
16350 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64  e called to find
16360 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
16370 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  * changes in the
16380 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
16390 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c  ompleted INSERT,
163a0 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
163b0 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  TE.** statement 
163c0 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  within the body 
163d0 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  of the same trig
163e0 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ger..** However,
163f0 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75   the number retu
16400 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e  rned does not in
16410 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a  clude changes.**
16420 20 63 61 75 73 65 64 20 62 79 20 73 75 62 74 72   caused by subtr
16430 69 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f  iggers since tho
16440 73 65 20 68 61 76 65 20 74 68 65 69 72 20 6f 77  se have their ow
16450 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a  n context.)^.**.
16460 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
16470 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
16480 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
16490 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
164a0 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
164b0 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61  a], and the [cha
164c0 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
164d0 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
164e0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
164f0 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
16500 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
16510 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
16520 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
16530 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
16540 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
16550 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
16560 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  * is unpredictab
16570 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
16580 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
16590 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71  lite3_changes(sq
165a0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
165b0 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20  CAPI3REF: Total 
165c0 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
165d0 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54  odified.**.** ^T
165e0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
165f0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
16600 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63  of row changes c
16610 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54  aused by [INSERT
16620 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f  ],.** [UPDATE] o
16630 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
16640 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20  ments since the 
16650 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
16660 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64  tion] was opened
16670 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74  ..** ^(The count
16680 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
16690 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
166a0 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c  es() includes al
166b0 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f  l changes.** fro
166c0 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52  m all [CREATE TR
166d0 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d  IGGER | trigger]
166e0 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68   contexts and ch
166f0 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a  anges made by.**
16700 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
16710 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c  tions]. However,
16720 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f  .** the count do
16730 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
16740 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69  hanges used to i
16750 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43  mplement [REPLAC
16760 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a  E] constraints,.
16770 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20  ** do rollbacks 
16780 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  or ABORT process
16790 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41  ing, or [DROP TA
167a0 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e  BLE] processing.
167b0 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64    The.** count d
167c0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
167d0 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68  rows of views th
167e0 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54  at fire an [INST
167f0 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c  EAD OF trigger],
16800 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68  .** though if th
16810 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  e INSTEAD OF tri
16820 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67  gger makes chang
16830 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74  es of its own, t
16840 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a  hose changes .**
16850 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a   are counted.)^.
16860 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
16870 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
16880 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20  function counts 
16890 74 68 65 20 63 68 61 6e 67 65 73 20 61 73 20 73  the changes as s
168a0 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74  oon as.** the st
168b0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b  atement that mak
168c0 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c  es them is compl
168d0 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73  eted (when the s
168e0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a  tatement handle.
168f0 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f 20  ** is passed to 
16900 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
16910 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
16920 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a  nalize()])..**.*
16930 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
16940 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
16950 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
16960 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
16970 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
16980 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e   the [total_chan
16990 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
169a0 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
169b0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
169c0 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
169d0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
169e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
169f0 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
16a00 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
16a10 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
16a20 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
16a30 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64  turned is unpred
16a40 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
16a50 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
16a60 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  nt sqlite3_total
16a70 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
16a80 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
16a90 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41  REF: Interrupt A
16aa0 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75   Long-Running Qu
16ab0 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ery.**.** ^This 
16ac0 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
16ad0 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
16ae0 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
16af0 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
16b00 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
16b10 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
16b20 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
16b30 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
16b40 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
16b50 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
16b60 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
16b70 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
16b80 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
16b90 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
16ba0 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
16bb0 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
16bc0 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
16bd0 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65  *.** ^It is safe
16be0 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
16bf0 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
16c00 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
16c10 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
16c20 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
16c30 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
16c40 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
16c50 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
16c60 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
16c70 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
16c80 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
16c90 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
16ca0 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
16cb0 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
16cc0 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
16cd0 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
16ce0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51  .**.** ^If an SQ
16cf0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
16d00 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
16d10 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
16d20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
16d30 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
16d40 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
16d50 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
16d60 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
16d70 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
16d80 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
16d90 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
16da0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51  on..**.** ^An SQ
16db0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
16dc0 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
16dd0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
16de0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
16df0 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72  ** ^If the inter
16e00 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
16e10 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
16e20 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
16e30 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
16e40 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
16e50 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
16e60 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
16e70 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
16e80 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
16e90 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
16ea0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
16eb0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
16ec0 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
16ed0 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
16ee0 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
16ef0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
16f00 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
16f10 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
16f20 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77  plete.  ^Any new
16f30 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
16f40 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
16f50 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
16f60 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
16f70 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
16f80 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
16f90 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
16fa0 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
16fb0 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
16fc0 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
16fd0 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
16fe0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
16ff0 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
17000 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d   ^New SQL statem
17010 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
17020 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
17030 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  he running state
17040 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68  ment count reach
17050 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e  es zero are.** n
17060 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74  ot effected by t
17070 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
17080 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61  rupt()..** ^A ca
17090 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
170a0 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
170b0 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
170c0 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
170d0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
170e0 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
170f0 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
17100 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
17110 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
17120 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
17130 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
17140 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
17150 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64  ..**.** If the d
17160 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17170 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
17180 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
17190 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e  pt()].** is runn
171a0 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69  ing then bad thi
171b0 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ngs will likely 
171c0 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20  happen..*/.void 
171d0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
171e0 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
171f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
17200 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
17210 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43  L Statement Is C
17220 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68  omplete.**.** Th
17230 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
17240 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63   useful during c
17250 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75  ommand-line inpu
17260 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69  t to determine i
17270 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  f the.** current
17280 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20  ly entered text 
17290 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20  seems to form a 
172a0 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
172b0 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20  tement or.** if 
172c0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74  additional input
172d0 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72   is needed befor
172e0 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65  e sending the te
172f0 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74  xt into.** SQLit
17300 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20  e for parsing.  
17310 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
17320 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20  return 1 if the 
17330 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
17340 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
17350 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
17360 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74  tement.  ^A stat
17370 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20  ement is judged 
17380 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  to be.** complet
17390 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74  e if it ends wit
173a0 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f  h a semicolon to
173b0 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ken and is not a
173c0 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20   prefix of a.** 
173d0 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41  well-formed CREA
173e0 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65  TE TRIGGER state
173f0 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f  ment.  ^Semicolo
17400 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65  ns that are embe
17410 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73  dded within.** s
17420 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f  tring literals o
17430 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66  r quoted identif
17440 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d  ier names or com
17450 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ments are not.**
17460 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b   independent tok
17470 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61  ens (they are pa
17480 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20  rt of the token 
17490 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72  in which they ar
174a0 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61  e.** embedded) a
174b0 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63  nd thus do not c
174c0 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d  ount as a statem
174d0 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ent terminator. 
174e0 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20   ^Whitespace.** 
174f0 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61  and comments tha
17500 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e  t follow the fin
17510 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65  al semicolon are
17520 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
17530 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
17540 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20  return 0 if the 
17550 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63  statement is inc
17560 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a  omplete.  ^If a.
17570 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
17580 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e  tion fails, then
17590 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73   SQLITE_NOMEM is
175a0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
175b0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
175c0 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68   do not parse th
175d0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
175e0 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f   thus.** will no
175f0 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74  t detect syntact
17600 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74  ically incorrect
17610 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66   SQL..**.** ^(If
17620 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20   SQLite has not 
17630 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64  been initialized
17640 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
17650 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72  initialize()] pr
17660 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b  ior .** to invok
17670 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ing sqlite3_comp
17680 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71  lete16() then sq
17690 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
176a0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
176b0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
176c0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  y sqlite3_comple
176d0 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74  te16().  If that
176e0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
176f0 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  fails,.** then t
17700 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
17710 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d  from sqlite3_com
17720 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62  plete16() will b
17730 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65  e non-zero.** re
17740 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
17750 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69  her or not the i
17760 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70  nput SQL is comp
17770 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  lete.)^.**.** Th
17780 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
17790 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20  te3_complete()] 
177a0 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
177b0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
177c0 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
177d0 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
177e0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
177f0 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  6()] must be a z
17800 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
17810 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  * UTF-16 string 
17820 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
17830 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rder..*/.int sql
17840 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
17850 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
17860 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
17870 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
17880 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
17890 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
178a0 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
178b0 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
178c0 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a  USY Errors.**.**
178d0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
178e0 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ets a callback f
178f0 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67  unction that mig
17900 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  ht be invoked wh
17910 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74  enever.** an att
17920 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
17930 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  open a database 
17940 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68  table that anoth
17950 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20  er thread.** or 
17960 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b  process has lock
17970 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
17980 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
17990 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53  is NULL, then [S
179a0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
179b0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
179c0 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75  CKED].** is retu
179d0 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
179e0 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69   upon encounteri
179f0 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49  ng the lock.  ^I
17a00 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
17a10 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  ack.** is not NU
17a20 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c  LL, then the cal
17a30 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69  lback might be i
17a40 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20  nvoked with two 
17a50 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
17a60 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
17a70 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79  ment to the busy
17a80 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f   handler is a co
17a90 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20  py of the void* 
17aa0 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a  pointer which.**
17ab0 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72   is the third ar
17ac0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
17ad0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
17ae0 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  .  ^The second a
17af0 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68  rgument to.** th
17b00 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  e busy handler c
17b10 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
17b20 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74  umber of times t
17b30 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e  hat the busy han
17b40 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e  dler has.** been
17b50 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69   invoked for thi
17b60 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  s locking event.
17b70 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73    ^If the.** bus
17b80 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
17b90 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
17ba0 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
17bb0 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
17bc0 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
17bd0 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
17be0 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
17bf0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
17c00 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
17c10 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
17c20 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
17c30 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72  ro, then another
17c40 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d   attempt.** is m
17c50 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20  ade to open the 
17c60 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61  database for rea
17c70 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63  ding and the cyc
17c80 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a  le repeats..**.*
17c90 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f  * The presence o
17ca0 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
17cb0 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e   does not guaran
17cc0 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c  tee that it will
17cd0 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77   be invoked.** w
17ce0 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63  hen there is loc
17cf0 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49  k contention. ^I
17d00 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69  f SQLite determi
17d10 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e  nes that invokin
17d20 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61  g the busy.** ha
17d30 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75  ndler could resu
17d40 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b  lt in a deadlock
17d50 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65  , it will go ahe
17d60 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  ad and return [S
17d70 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f  QLITE_BUSY].** o
17d80 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
17d90 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64  BLOCKED] instead
17da0 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65   of invoking the
17db0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
17dc0 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65  * Consider a sce
17dd0 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20  nario where one 
17de0 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
17df0 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74  ng a read lock t
17e00 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79  hat.** it is try
17e10 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ing to promote t
17e20 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  o a reserved loc
17e30 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e  k and.** a secon
17e40 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  d process is hol
17e50 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20  ding a reserved 
17e60 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20  lock that it is 
17e70 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f  trying.** to pro
17e80 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75  mote to an exclu
17e90 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20  sive lock.  The 
17ea0 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61  first process ca
17eb0 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20  nnot proceed.** 
17ec0 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
17ed0 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63  ocked by the sec
17ee0 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f  ond and the seco
17ef0 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  nd process canno
17f00 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63  t.** proceed bec
17f10 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
17f20 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e  ed by the first.
17f30 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73    If both proces
17f40 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68  ses.** invoke th
17f50 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c  e busy handlers,
17f60 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61   neither will ma
17f70 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e  ke any progress.
17f80 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20    Therefore,.** 
17f90 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b  SQLite returns [
17fa0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72  SQLITE_BUSY] for
17fb0 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
17fc0 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20  ss, hoping that 
17fd0 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64  this.** will ind
17fe0 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72  uce the first pr
17ff0 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65  ocess to release
18000 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61   its read lock a
18010 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20  nd allow.** the 
18020 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74  second process t
18030 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a  o proceed..**.**
18040 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75   ^The default bu
18050 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
18060 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
18070 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72  [SQLITE_BUSY] er
18080 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64  ror is converted
18090 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   to [SQLITE_IOER
180a0 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68  R_BLOCKED].** wh
180b0 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20  en SQLite is in 
180c0 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20  the middle of a 
180d0 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f  large transactio
180e0 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a  n where all the.
180f0 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20  ** changes will 
18100 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65  not fit into the
18110 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65   in-memory cache
18120 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a  .  SQLite will.*
18130 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61  * already hold a
18140 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f   RESERVED lock o
18150 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
18160 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64  ile, but it need
18170 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  s.** to promote 
18180 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43  this lock to EXC
18190 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69  LUSIVE so that i
181a0 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68  t can spill cach
181b0 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20  e.** pages into 
181c0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
181d0 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74  e without harm t
181e0 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20  o concurrent.** 
181f0 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74  readers.  ^If it
18200 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72   is unable to pr
18210 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20  omote the lock, 
18220 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  then the in-memo
18230 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c  ry.** cache will
18240 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69   be left in an i
18250 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74  nconsistent stat
18260 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72  e and so the err
18270 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72  or.** code is pr
18280 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20  omoted from the 
18290 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67  relatively benig
182a0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
182b0 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  to.** the more s
182c0 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f  evere [SQLITE_IO
182d0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e  ERR_BLOCKED].  ^
182e0 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20  This error code 
182f0 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72  promotion.** for
18300 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63  ces an automatic
18310 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   rollback of the
18320 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74   changes.  See t
18330 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f  he.** <a href="/
18340 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43  cvstrac/wiki?p=C
18350 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
18360 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a  ngBusyError">.**
18370 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f   CorruptionFollo
18380 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61  wingBusyError</a
18390 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20  > wiki page for 
183a0 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20  a discussion of 
183b0 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69  why.** this is i
183c0 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20  mportant..**.** 
183d0 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
183e0 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
183f0 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65  y handler define
18400 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64  d for each.** [d
18410 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18420 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20  on].  Setting a 
18430 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
18440 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70   clears any.** p
18450 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61  reviously set ha
18460 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20  ndler.)^  ^Note 
18470 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  that calling [sq
18480 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
18490 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c  ut()].** will al
184a0 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20  so set or clear 
184b0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
184c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79  ..**.** The busy
184d0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
184e0 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63   not take any ac
184f0 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69  tions which modi
18500 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  fy the.** databa
18510 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
18520 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
18530 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e  usy handler.  An
18540 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a  y such actions.*
18550 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  * result in unde
18560 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
18570 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61  ** .** A busy ha
18580 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63  ndler must not c
18590 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
185a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
185b0 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  or [prepared sta
185c0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76  tement] that inv
185d0 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
185e0 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ndler..*/.int sq
185f0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
18600 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
18610 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20  (*)(void*,int), 
18620 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
18630 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42  API3REF: Set A B
18640 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a  usy Timeout.**.*
18650 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
18660 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
18670 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
18680 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
18690 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
186a0 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
186b0 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
186c0 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
186d0 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  d.  ^The handler
186e0 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  .** will sleep m
186f0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
18700 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73  til at least "ms
18710 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
18720 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61  f sleeping.** ha
18730 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20  ve accumulated. 
18740 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74   ^After at least
18750 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
18760 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a  ds of sleeping,.
18770 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72  ** the handler r
18780 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63  eturns 0 which c
18790 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
187a0 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
187b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
187c0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
187d0 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a  RR_BLOCKED]..**.
187e0 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
187f0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
18800 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
18810 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
18820 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
18830 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
18840 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ers..**.** ^(The
18850 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
18860 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
18870 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
18880 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
18890 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
188a0 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d  ny any given mom
188b0 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72  ent.  If another
188c0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a   busy handler.**
188d0 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75   was defined  (u
188e0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  sing [sqlite3_bu
188f0 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70  sy_handler()]) p
18900 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  rior to calling.
18910 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  ** this routine,
18920 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79   that other busy
18930 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
18940 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71  red.)^.*/.int sq
18950 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
18960 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ut(sqlite3*, int
18970 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   ms);../*.** CAP
18980 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e  I3REF: Convenien
18990 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20  ce Routines For 
189a0 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a  Running Queries.
189b0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  **.** This is a 
189c0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
189d0 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76   that is preserv
189e0 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
189f0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
18a00 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69  ** Use of this i
18a10 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
18a20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a  recommended..**.
18a30 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41  ** Definition: A
18a40 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65   <b>result table
18a50 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64  </b> is memory d
18a60 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72  ata structure cr
18a70 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  eated by the.** 
18a80 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
18a90 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  le()] interface.
18aa0 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65    A result table
18ab0 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20   records the.** 
18ac0 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72  complete query r
18ad0 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20  esults from one 
18ae0 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e  or more queries.
18af0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
18b00 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61   conceptually ha
18b10 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  s a number of ro
18b20 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20  ws and columns. 
18b30 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75   But.** these nu
18b40 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61  mbers are not pa
18b50 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  rt of the result
18b60 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20   table itself.  
18b70 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73  These.** numbers
18b80 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65   are obtained se
18b90 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e  parately.  Let N
18ba0 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
18bb0 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20  f rows.** and M 
18bc0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
18bd0 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20   columns..**.** 
18be0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  A result table i
18bf0 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
18c00 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
18c10 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
18c20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72  strings..** Ther
18c30 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c  e are (N+1)*M el
18c40 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72  ements in the ar
18c50 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20  ray.  The first 
18c60 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74  M pointers point
18c70 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  .** to zero-term
18c80 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
18c90 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65  hat  contain the
18ca0 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f   names of the co
18cb0 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65  lumns..** The re
18cc0 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20  maining entries 
18cd0 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65  all point to que
18ce0 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c  ry results.  NUL
18cf0 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a  L values result.
18d00 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74  ** in NULL point
18d10 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ers.  All other 
18d20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68  values are in th
18d30 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  eir UTF-8 zero-t
18d40 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
18d50 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69  ing representati
18d60 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62  on as returned b
18d70 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
18d80 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
18d90 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
18da0 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66  might consist of
18db0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d   one or more mem
18dc0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
18dd0 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
18de0 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73  fe to pass a res
18df0 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74  ult table direct
18e00 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ly to [sqlite3_f
18e10 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73  ree()]..** A res
18e20 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  ult table should
18e30 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
18e40 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
18e50 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
18e60 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d  .** ^(As an exam
18e70 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ple of the resul
18e80 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20  t table format, 
18e90 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20  suppose a query 
18ea0 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20  result.** is as 
18eb0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
18ec0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
18ed0 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20  .**        Name 
18ee0 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20         | Age.** 
18ef0 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d         ---------
18f00 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a  --------------.*
18f10 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20  *        Alice  
18f20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20       | 43.**    
18f30 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20      Bob         
18f40 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43  | 28.**        C
18f50 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a  indy       | 21.
18f60 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
18f70 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
18f80 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d  re are two colum
18f90 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72  n (M==2) and thr
18fa0 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20  ee rows (N==3). 
18fb0 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73   Thus the.** res
18fc0 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20  ult table has 8 
18fd0 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73  entries.  Suppos
18fe0 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  e the result tab
18ff0 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20  le is stored.** 
19000 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65  in an array name
19010 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65  s azResult.  The
19020 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73  n azResult holds
19030 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a   this content:.*
19040 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
19050 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
19060 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d   azResult&#91;0]
19070 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20   = "Name";.**   
19080 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
19090 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a  1;1] = "Age";.**
190a0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
190b0 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65  &#91;2] = "Alice
190c0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
190d0 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22  esult&#91;3] = "
190e0 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  43";.**        a
190f0 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d  zResult&#91;4] =
19100 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20   "Bob";.**      
19110 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35    azResult&#91;5
19120 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20  ] = "28";.**    
19130 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
19140 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a  ;6] = "Cindy";.*
19150 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
19160 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b  t&#91;7] = "21";
19170 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
19180 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
19190 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
191a0 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f  _table() functio
191b0 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20  n evaluates one 
191c0 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63  or more.** semic
191d0 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53  olon-separated S
191e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  QL statements in
191f0 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
19200 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74  ated UTF-8.** st
19210 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20  ring of its 2nd 
19220 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
19230 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74  turns a result t
19240 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70  able to the.** p
19250 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20  ointer given in 
19260 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
19270 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  r..**.** After t
19280 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68  he application h
19290 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
192a0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
192b0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
192c0 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74  le(),.** it must
192d0 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74   pass the result
192e0 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74   table pointer t
192f0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  o sqlite3_free_t
19300 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20  able() in order 
19310 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  to.** release th
19320 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
19330 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63  s malloced.  Bec
19340 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20  ause of the way 
19350 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
19360 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e  malloc()] happen
19370 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33  s within sqlite3
19380 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68  _get_table(), th
19390 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e  e calling.** fun
193a0 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74  ction must not t
193b0 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69  ry to call [sqli
193c0 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65  te3_free()] dire
193d0 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b  ctly.  Only.** [
193e0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
193f0 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f  le()] is able to
19400 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
19410 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64  ory properly and
19420 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54   safely..**.** T
19430 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
19440 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  able() interface
19450 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
19460 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f  as a wrapper aro
19470 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
19480 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71  exec()].  The sq
19490 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
194a0 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e  ) routine does n
194b0 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a  ot have access.*
194c0 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61  * to any interna
194d0 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  l data structure
194e0 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74  s of SQLite.  It
194f0 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70   uses only the p
19500 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61  ublic.** interfa
19510 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  ce defined here.
19520 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e    As a consequen
19530 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20  ce, errors that 
19540 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20  occur in the.** 
19550 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75  wrapper layer ou
19560 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74  tside of the int
19570 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65  ernal [sqlite3_e
19580 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20  xec()] call are 
19590 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64  not.** reflected
195a0 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
195b0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
195c0 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a  _errcode()] or.*
195d0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
195e0 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  g()]..*/.int sql
195f0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a  ite3_get_table(.
19600 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
19610 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
19620 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
19630 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
19640 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f  l,     /* SQL to
19650 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
19660 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65  .  char ***pazRe
19670 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75  sult,    /* Resu
19680 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79  lts of the query
19690 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77   */.  int *pnRow
196a0 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
196b0 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
196c0 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72  rows written her
196d0 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f  e */.  int *pnCo
196e0 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20  lumn,        /* 
196f0 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
19700 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e   columns written
19710 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20   here */.  char 
19720 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20  **pzErrmsg      
19730 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
19740 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
19750 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
19760 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a  ee_table(char **
19770 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  result);../*.** 
19780 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74  CAPI3REF: Format
19790 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74  ted String Print
197a0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
197b0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
197c0 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b  es are work-alik
197d0 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74  es of the "print
197e0 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66  f()" family of f
197f0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d  unctions.** from
19800 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
19810 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  library..**.** ^
19820 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  The sqlite3_mpri
19830 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
19840 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75  3_vmprintf() rou
19850 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69  tines write thei
19860 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  r.** results int
19870 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
19880 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
19890 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68  malloc()]..** Th
198a0 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
198b0 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20  ed by these two 
198c0 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
198d0 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62  be.** released b
198e0 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  y [sqlite3_free(
198f0 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69  )].  ^Both routi
19900 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
19910 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
19920 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
19930 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
19940 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
19950 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
19960 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
19970 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28  string..**.** ^(
19980 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  The sqlite3_snpr
19990 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
199a0 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e  s similar to "sn
199b0 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a  printf()" from.*
199c0 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  * the standard C
199d0 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72   library.  The r
199e0 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e  esult is written
199f0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66   into the.** buf
19a00 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20  fer supplied as 
19a10 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
19a20 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20  eter whose size 
19a30 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74  is given by.** t
19a40 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
19a50 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  er. Note that th
19a60 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a  e order of the.*
19a70 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61  * first two para
19a80 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73  meters is revers
19a90 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66  ed from snprintf
19aa0 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61  ().)^  This is a
19ab0 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20  n.** historical 
19ac0 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61  accident that ca
19ad0 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69  nnot be fixed wi
19ae0 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a  thout breaking.*
19af0 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
19b00 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f  atibility.  ^(No
19b10 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c  te also that sql
19b20 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
19b30 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ** returns a poi
19b40 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66  nter to its buff
19b50 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  er instead of th
19b60 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
19b70 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c  haracters actual
19b80 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ly written into 
19b90 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57  the buffer.)^  W
19ba0 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20  e admit that.** 
19bb0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
19bc0 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e  aracters written
19bd0 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65   would be a more
19be0 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a   useful return.*
19bf0 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63  * value but we c
19c00 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
19c10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
19c20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
19c30 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74  ntf().** now wit
19c40 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f  hout breaking co
19c50 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
19c60 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74  ** ^As long as t
19c70 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69  he buffer size i
19c80 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a  s greater than z
19c90 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70  ero, sqlite3_snp
19ca0 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61  rintf().** guara
19cb0 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62  ntees that the b
19cc0 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20  uffer is always 
19cd0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
19ce0 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20    ^The first.** 
19cf0 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73  parameter "n" is
19d00 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20   the total size 
19d10 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69  of the buffer, i
19d20 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66  ncluding space f
19d30 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74  or.** the zero t
19d40 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74  erminator.  So t
19d50 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e  he longest strin
19d60 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f  g that can be co
19d70 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74  mpletely.** writ
19d80 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20  ten will be n-1 
19d90 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
19da0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
19db0 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
19dc0 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20  ne is a varargs 
19dd0 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74  version of sqlit
19de0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a  e3_snprintf()..*
19df0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
19e00 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e  nes all implemen
19e10 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61  t some additiona
19e20 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20  l formatting.** 
19e30 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65  options that are
19e40 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73   useful for cons
19e50 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61  tructing SQL sta
19e60 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20  tements..** All 
19e70 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69  of the usual pri
19e80 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67  ntf() formatting
19e90 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20   options apply. 
19ea0 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68   In addition, th
19eb0 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25  ere.** is are "%
19ec0 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25  q", "%Q", and "%
19ed0 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  z" options..**.*
19ee0 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f  * ^(The %q optio
19ef0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20  n works like %s 
19f00 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74  in that it subst
19f10 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72  itutes a nul-ter
19f20 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
19f30 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d  g from the argum
19f40 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25  ent list.  But %
19f50 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65  q also doubles e
19f60 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63  very '\'' charac
19f70 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65  ter..** %q is de
19f80 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69  signed for use i
19f90 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c  nside a string l
19fa0 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f  iteral.)^  By do
19fb0 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27  ubling each '\''
19fc0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74  .** character it
19fd0 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68   escapes that ch
19fe0 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f  aracter and allo
19ff0 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65  ws it to be inse
1a000 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  rted into.** the
1a010 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46   string..**.** F
1a020 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75  or example, assu
1a030 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61  me the string va
1a040 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e  riable zText con
1a050 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f  tains text as fo
1a060 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1a070 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1a080 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d  *  char *zText =
1a090 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64   "It's a happy d
1a0a0 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!";.** </pre><
1a0b0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1a0c0 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74  ** One can use t
1a0d0 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53  his text in an S
1a0e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
1a0f0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1a100 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1a110 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
1a120 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
1a130 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
1a140 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27  able VALUES('%q'
1a150 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
1a160 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
1a170 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
1a180 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
1a190 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
1a1a0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1a1b0 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
1a1c0 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69  e %q format stri
1a1d0 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20  ng is used, the 
1a1e0 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69  '\'' character i
1a1f0 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73  n zText.** is es
1a200 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51  caped and the SQ
1a210 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61  L generated is a
1a220 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1a230 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1a240 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
1a250 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
1a260 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20  ('It''s a happy 
1a270 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e  day!').** </pre>
1a280 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1a290 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72  .** This is corr
1a2a0 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65  ect.  Had we use
1a2b0 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20  d %s instead of 
1a2c0 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65  %q, the generate
1a2d0 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68  d SQL.** would h
1a2e0 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20  ave looked like 
1a2f0 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  this:.**.** <blo
1a300 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1a310 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1a320 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1a330 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
1a340 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1a350 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1a360 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70  his second examp
1a370 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e  le is an SQL syn
1a380 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61  tax error.  As a
1a390 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f   general rule yo
1a3a0 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61  u should.** alwa
1a3b0 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61  ys use %q instea
1a3c0 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73  d of %s when ins
1a3d0 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f  erting text into
1a3e0 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1a3f0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  l..**.** ^(The %
1a400 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  Q option works l
1a410 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74  ike %q except it
1a420 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c   also adds singl
1a430 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a  e quotes around.
1a440 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f  ** the outside o
1a450 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69  f the total stri
1a460 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ng.  Additionall
1a470 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  y, if the parame
1a480 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72  ter in the.** ar
1a490 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61  gument list is a
1a4a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25   NULL pointer, %
1a4b0 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68  Q substitutes th
1a4c0 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77  e text "NULL" (w
1a4d0 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65  ithout.** single
1a4e0 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c   quotes).)^  So,
1a4f0 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e   for example, on
1a500 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a  e could say:.**.
1a510 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1a520 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1a530 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
1a540 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
1a550 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
1a560 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  %Q)", zText);.**
1a570 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
1a580 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
1a590 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
1a5a0 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
1a5b0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1a5c0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  >.**.** The code
1a5d0 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64   above will rend
1a5e0 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c  er a correct SQL
1a5f0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
1a600 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62  e zSQL.** variab
1a610 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a  le even if the z
1a620 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73  Text variable is
1a630 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1a640 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a  .**.** ^(The "%z
1a650 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
1a660 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22  ion works like "
1a670 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65  %s" but with the
1a680 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61  .** addition tha
1a690 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69  t after the stri
1a6a0 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64  ng has been read
1a6b0 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f   and copied into
1a6c0 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20  .** the result, 
1a6d0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1a6e0 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68   is called on th
1a6f0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29  e input string.)
1a700 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74  ^.*/.char *sqlit
1a710 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
1a720 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61   char*,...);.cha
1a730 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  r *sqlite3_vmpri
1a740 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1a750 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20   va_list);.char 
1a760 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  *sqlite3_snprint
1a770 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
1a780 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63  t char*, ...);.c
1a790 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e  har *sqlite3_vsn
1a7a0 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
1a7b0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  ,const char*, va
1a7c0 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _list);../*.** C
1a7d0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
1a7e0 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79  Allocation Subsy
1a7f0 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  stem.**.** The S
1a800 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20  QLite core uses 
1a810 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74  these three rout
1a820 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20  ines for all of 
1a830 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72  its own.** inter
1a840 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  nal memory alloc
1a850 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f  ation needs. "Co
1a860 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69  re" in the previ
1a870 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20  ous sentence.** 
1a880 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
1a890 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
1a8a0 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69  m specific VFS i
1a8b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
1a8c0 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56  The.** Windows V
1a8d0 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d  FS uses native m
1a8e0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
1a8f0 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72  () for some oper
1a900 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ations..**.** ^T
1a910 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
1a920 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  c() routine retu
1a930 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1a940 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d   a block.** of m
1a950 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e  emory at least N
1a960 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68   bytes in length
1a970 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
1a980 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
1a990 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
1a9a0 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  c() is unable to
1a9b0 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65   obtain sufficie
1a9c0 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72  nt free.** memor
1a9d0 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20  y, it returns a 
1a9e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
1a9f0 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
1aa00 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   N to.** sqlite3
1aa10 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  _malloc() is zer
1aa20 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68  o or negative th
1aa30 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  en sqlite3_mallo
1aa40 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  c() returns.** a
1aa50 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1aa60 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  *.** ^Calling sq
1aa70 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74  lite3_free() wit
1aa80 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76  h a pointer prev
1aa90 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a  iously returned.
1aaa0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ** by sqlite3_ma
1aab0 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
1aac0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65  3_realloc() rele
1aad0 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  ases that memory
1aae0 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d   so.** that it m
1aaf0 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20  ight be reused. 
1ab00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72   ^The sqlite3_fr
1ab10 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  ee() routine is.
1ab20 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73  ** a no-op if is
1ab30 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
1ab40 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61  ULL pointer.  Pa
1ab50 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
1ab60 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  nter.** to sqlit
1ab70 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72  e3_free() is har
1ab80 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65  mless.  After be
1ab90 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72  ing freed, memor
1aba0 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74  y.** should neit
1abb0 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20  her be read nor 
1abc0 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72  written.  Even r
1abd0 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c  eading previousl
1abe0 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72  y freed.** memor
1abf0 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  y might result i
1ac00 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
1ac10 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
1ac20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a  severe error..**
1ac30 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
1ac40 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
1ac50 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
1ac60 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
1ac70 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
1ac80 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
1ac90 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
1aca0 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
1acb0 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
1acc0 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
1acd0 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
1ace0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
1acf0 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  alloc()..**.** ^
1ad00 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  (The sqlite3_rea
1ad10 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65  lloc() interface
1ad20 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
1ad30 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
1ad40 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1ad50 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20   to be at least 
1ad60 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e  N bytes, where N
1ad70 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e   is the.** secon
1ad80 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
1ad90 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
1ada0 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65  ion to be resize
1adb0 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  d is the first.*
1adc0 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e  * parameter.)^ ^
1add0 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61   If the first pa
1ade0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1adf0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
1ae00 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1ae10 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76  r then its behav
1ae20 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ior is identical
1ae30 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   to calling.** s
1ae40 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1ae50 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
1ae60 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1ae70 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1ae80 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68  loc()..** ^If th
1ae90 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1aea0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1aeb0 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
1aec0 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74  or.** negative t
1aed0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1aee0 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20   is exactly the 
1aef0 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a  same as calling.
1af00 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
1af10 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68  P) where P is th
1af20 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1af30 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1af40 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69  lloc()..** ^sqli
1af50 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
1af60 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1af70 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  to a memory allo
1af80 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20  cation.** of at 
1af90 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
1afa0 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66   size or NULL if
1afb0 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f   sufficient memo
1afc0 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  ry is unavailabl
1afd0 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74  e..** ^If M is t
1afe0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70  he size of the p
1aff0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  rior allocation,
1b000 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62   then min(N,M) b
1b010 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70  ytes.** of the p
1b020 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
1b030 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20  are copied into 
1b040 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
1b050 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64   buffer returned
1b060 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72  .** by sqlite3_r
1b070 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65  ealloc() and the
1b080 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1b090 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  n is freed..** ^
1b0a0 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  If sqlite3_reall
1b0b0 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  oc() returns NUL
1b0c0 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f  L, then the prio
1b0d0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  r allocation.** 
1b0e0 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a  is not freed..**
1b0f0 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
1b100 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1b110 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  te3_malloc() and
1b120 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1b130 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ().** is always 
1b140 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65  aligned to at le
1b150 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f  ast an 8 byte bo
1b160 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a  undary, or to a.
1b170 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61  ** 4 byte bounda
1b180 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ry if the [SQLIT
1b190 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44  E_4_BYTE_ALIGNED
1b1a0 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65  _MALLOC] compile
1b1b0 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20  -time.** option 
1b1c0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  is used..**.** I
1b1d0 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
1b1e0 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31   3.5.0 and 3.5.1
1b1f0 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c  , it was possibl
1b200 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74  e to define.** t
1b210 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d  he SQLITE_OMIT_M
1b220 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e  EMORY_ALLOCATION
1b230 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75   which would cau
1b240 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a  se the built-in.
1b250 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
1b260 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  n of these routi
1b270 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65  nes to be omitte
1b280 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c  d.  That capabil
1b290 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e  ity.** is no lon
1b2a0 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f  ger provided.  O
1b2b0 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  nly built-in mem
1b2c0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63  ory allocators c
1b2d0 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a  an be used..**.*
1b2e0 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74  * Prior to SQLit
1b2f0 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30  e version 3.7.10
1b300 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53  , the Windows OS
1b310 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
1b320 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73   called.** the s
1b330 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61  ystem malloc() a
1b340 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74  nd free() direct
1b350 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69  ly when converti
1b360 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20  ng.** filenames 
1b370 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d  between the UTF-
1b380 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  8 encoding used 
1b390 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
1b3a0 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61   whatever filena
1b3b0 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  me encoding is u
1b3c0 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69  sed by the parti
1b3d0 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a  cular Windows.**
1b3e0 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20   installation.  
1b3f0 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
1b400 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 64 65  n errors were de
1b410 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74  tected, but.** t
1b420 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 74 65  hey were reporte
1b430 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54  d back as [SQLIT
1b440 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a  E_CANTOPEN] or.*
1b450 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  * [SQLITE_IOERR]
1b460 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51   rather than [SQ
1b470 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
1b480 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61  ** The pointer a
1b490 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c  rguments to [sql
1b4a0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64  ite3_free()] and
1b4b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1b4c0 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  c()].** must be 
1b4d0 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65  either NULL or e
1b4e0 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74  lse pointers obt
1b4f0 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69  ained from a pri
1b500 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  or.** invocation
1b510 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
1b520 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  loc()] or [sqlit
1b530 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68  e3_realloc()] th
1b540 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79  at have.** not y
1b550 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  et been released
1b560 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
1b570 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
1b580 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61   read or write a
1b590 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20  ny part of.** a 
1b5a0 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
1b5b0 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
1b5c0 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67  n released using
1b5d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
1b5e0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
1b5f0 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  _realloc()]..*/.
1b600 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
1b610 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20  lloc(int);.void 
1b620 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
1b630 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f  (void*, int);.vo
1b640 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
1b650 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1b660 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
1b670 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
1b680 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  tics.**.** SQLit
1b690 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65  e provides these
1b6a0 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20   two interfaces 
1b6b0 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e  for reporting on
1b6c0 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f   the status.** o
1b6d0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
1b6e0 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
1b6f0 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20  e3_free()], and 
1b700 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1b710 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c  ()].** routines,
1b720 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20   which form the 
1b730 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
1b740 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
1b750 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  stem..**.** ^The
1b760 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1b770 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65  _used()] routine
1b780 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1b790 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20  ber of bytes.** 
1b7a0 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e  of memory curren
1b7b0 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  tly outstanding 
1b7c0 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f  (malloced but no
1b7d0 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68  t freed)..** ^Th
1b7e0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
1b7f0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72  y_highwater()] r
1b800 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
1b810 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61  he maximum.** va
1b820 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
1b830 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73  memory_used()] s
1b840 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61  ince the high-wa
1b850 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20  ter mark.** was 
1b860 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68  last reset.  ^Th
1b870 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
1b880 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d by [sqlite3_me
1b890 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64  mory_used()] and
1b8a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
1b8b0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1b8c0 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65   include any ove
1b8d0 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62  rhead.** added b
1b8e0 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20  y SQLite in its 
1b8f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1b900 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
1b910 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74  c()],.** but not
1b920 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20   overhead added 
1b930 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72  by the any under
1b940 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62  lying system lib
1b950 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  rary.** routines
1b960 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d   that [sqlite3_m
1b970 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c  alloc()] may cal
1b980 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
1b990 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20  mory high-water 
1b9a0 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f  mark is reset to
1b9b0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
1b9c0 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  ue of.** [sqlite
1b9d0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1b9e0 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
1b9f0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  the parameter to
1ba00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
1ba10 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1ba20 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20   is true.  ^The 
1ba30 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
1ba40 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  * by [sqlite3_me
1ba50 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31  mory_highwater(1
1ba60 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77  )] is the high-w
1ba70 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69  ater mark.** pri
1ba80 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e  or to the reset.
1ba90 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
1baa0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
1bab0 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c  _used(void);.sql
1bac0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1bad0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1bae0 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
1baf0 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
1bb00 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
1bb10 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
1bb20 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  tor.**.** SQLite
1bb30 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
1bb40 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
1bb50 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
1bb60 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
1bb70 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
1bb80 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
1bb90 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
1bba0 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
1bbb0 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
1bbc0 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
1bbd0 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
1bbe0 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
1bbf0 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
1bc00 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
1bc10 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
1bc20 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
1bc30 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
1bc40 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
1bc50 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
1bc60 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
1bc70 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
1bc80 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
1bc90 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
1bca0 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73   ^A call to this
1bcb0 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
1bcc0 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  N bytes of rando
1bcd0 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
1bce0 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r P..**.** ^The 
1bcf0 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20  first time this 
1bd00 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b  routine is invok
1bd10 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72  ed (either inter
1bd20 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74  nally or by.** t
1bd30 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20  he application) 
1bd40 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64  the PRNG is seed
1bd50 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
1bd60 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ess obtained.** 
1bd70 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d  from the xRandom
1bd80 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  ness method of t
1bd90 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1bda0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
1bdb0 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73  .** ^On all subs
1bdc0 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
1bdd0 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72  ns, the pseudo-r
1bde0 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e  andomness is gen
1bdf0 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e  erated.** intern
1be00 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74  ally and without
1be10 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65   recourse to the
1be20 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
1be30 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65  Randomness.** me
1be40 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  thod..*/.void sq
1be50 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
1be60 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29  (int N, void *P)
1be70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1be80 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
1be90 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61  Authorization Ca
1bea0 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
1beb0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
1bec0 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69  sters an authori
1bed0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74  zer callback wit
1bee0 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
1bef0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1bf00 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65  ection], supplie
1bf10 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
1bf20 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
1bf30 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1bf40 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1bf50 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
1bf60 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
1bf70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
1bf80 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
1bf90 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
1bfa0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1bfb0 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
1bfc0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
1bfd0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
1bfe0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e  pare16_v2()].  ^
1bff0 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f  At various.** po
1c000 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20  ints during the 
1c010 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63  compilation proc
1c020 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73  ess, as logic is
1c030 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a   being created.*
1c040 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  * to perform var
1c050 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68  ious actions, th
1c060 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1c070 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1c080 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68   to.** see if th
1c090 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20  ose actions are 
1c0a0 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61  allowed.  ^The a
1c0b0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1c0c0 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ck should.** ret
1c0d0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
1c0e0 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74  to allow the act
1c0f0 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e  ion, [SQLITE_IGN
1c100 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77  ORE] to disallow
1c110 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
1c120 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f   action but allo
1c130 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  w the SQL statem
1c140 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  ent to continue 
1c150 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  to be.** compile
1c160 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  d, or [SQLITE_DE
1c170 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65  NY] to cause the
1c180 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74   entire SQL stat
1c190 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72  ement to be.** r
1c1a0 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20  ejected with an 
1c1b0 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20  error.  ^If the 
1c1c0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1c1d0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
1c1e0 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
1c1f0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
1c200 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
1c210 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
1c220 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b  Y].** then the [
1c230 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1c240 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
1c250 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
1c260 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
1c270 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
1c280 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
1c290 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
1c2a0 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
1c2b0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
1c2c0 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
1c2d0 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
1c2e0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
1c2f0 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20   ok.  ^When the 
1c300 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1c310 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
1c320 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1c330 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1c340 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
1c350 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
1c360 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
1c370 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
1c380 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
1c390 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61  e explaining tha
1c3a0 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64  t.** access is d
1c3b0 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54  enied. .**.** ^T
1c3c0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1c3d0 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
1c3e0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1c3f0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
1c400 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
1c410 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
1c420 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1c430 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68  ) interface. ^Th
1c440 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1c450 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  er.** to the cal
1c460 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
1c470 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  ger [SQLITE_COPY
1c480 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
1c490 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
1c4a0 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  * the particular
1c4b0 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
1c4c0 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74  thorized. ^The t
1c4d0 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78  hird through six
1c4e0 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  th parameters.**
1c4f0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1c500 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   are zero-termin
1c510 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
1c520 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69  t contain additi
1c530 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20  onal.** details 
1c540 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
1c550 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
1c560 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
1c570 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
1c580 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a  [SQLITE_READ].**
1c590 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
1c5a0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
1c5b0 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
1c5c0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
1c5d0 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65  statement] state
1c5e0 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63  ment is construc
1c5f0 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74  ted to substitut
1c600 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75  e.** a NULL valu
1c610 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  e in place of th
1c620 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  e table column t
1c630 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a  hat would have.*
1c640 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b  * been read if [
1c650 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
1c660 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54  een returned.  T
1c670 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  he [SQLITE_IGNOR
1c680 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e  E].** return can
1c690 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79   be used to deny
1c6a0 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73   an untrusted us
1c6b0 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64  er access to ind
1c6c0 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d  ividual.** colum
1c6d0 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a  ns of a table..*
1c6e0 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
1c6f0 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
1c700 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
1c710 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1c720 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
1c730 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
1c740 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
1c750 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
1c760 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
1c770 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
1c780 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
1c790 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
1c7a0 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
1c7b0 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
1c7c0 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
1c7d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1c7e0 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
1c7f0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
1c800 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
1c810 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
1c820 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
1c830 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1c840 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
1c850 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
1c860 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
1c870 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
1c880 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
1c890 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
1c8a0 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
1c8b0 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
1c8c0 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
1c8d0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
1c8e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
1c8f0 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
1c900 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
1c910 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
1c920 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
1c930 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
1c940 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1c950 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
1c960 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
1c970 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
1c980 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
1c990 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
1c9a0 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
1c9b0 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
1c9c0 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
1c9d0 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
1c9e0 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
1c9f0 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
1ca00 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
1ca10 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
1ca20 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
1ca30 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
1ca40 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
1ca50 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
1ca60 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
1ca70 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
1ca80 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
1ca90 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
1caa0 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
1cab0 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
1cac0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
1cad0 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
1cae0 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
1caf0 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
1cb00 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
1cb10 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
1cb20 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
1cb30 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
1cb40 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73  **.** ^(Only a s
1cb50 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
1cb60 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
1cb70 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
1cb80 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
1cb90 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
1cba0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
1cbb0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
1cbc0 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
1cbd0 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20  evious call.)^  
1cbe0 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74  ^Disable the aut
1cbf0 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
1cc00 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
1cc10 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
1cc20 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
1cc30 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
1cc40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
1cc50 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
1cc60 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
1cc70 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
1cc80 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
1cc90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1cca0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1ccb0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1ccc0 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  back..** Note th
1ccd0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
1cce0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
1ccf0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
1cd00 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
1cd10 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1cd20 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
1cd30 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
1cd40 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
1cd50 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57  agraph..**.** ^W
1cd60 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
1cd70 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73  pare_v2()] is us
1cd80 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20  ed to prepare a 
1cd90 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a  statement, the.*
1cda0 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68  * statement migh
1cdb0 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64  t be re-prepared
1cdc0 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33   during [sqlite3
1cdd0 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20  _step()] due to 
1cde0 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61  a .** schema cha
1cdf0 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  nge.  Hence, the
1ce00 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
1ce10 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20  uld ensure that 
1ce20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61  the.** correct a
1ce30 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1ce40 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c  ck remains in pl
1ce50 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b  ace during the [
1ce60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1ce70 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
1ce80 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
1ce90 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1cea0 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
1ceb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1cec0 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
1ced0 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
1cee0 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
1cef0 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
1cf00 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
1cf10 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
1cf20 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c  te3_step()], unl
1cf30 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64  ess.** as stated
1cf40 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
1cf50 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69   paragraph, sqli
1cf60 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b  te3_step() invok
1cf70 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  es.** sqlite3_pr
1cf80 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65  epare_v2() to re
1cf90 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
1cfa0 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65  ent after a sche
1cfb0 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e  ma change..*/.in
1cfc0 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
1cfd0 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
1cfe0 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
1cff0 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
1d000 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1d010 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
1d020 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
1d030 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
1d040 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
1d050 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
1d060 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a  r Return Codes.*
1d070 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
1d080 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1d090 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
1d0a0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
1d0b0 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
1d0c0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
1d0d0 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
1d0e0 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
1d0f0 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
1d100 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
1d110 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
1d120 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
1d130 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
1d140 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
1d150 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
1d160 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
1d170 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
1d180 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
1d190 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ion..**.** Note 
1d1a0 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f  that SQLITE_IGNO
1d1b0 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  RE is also used 
1d1c0 61 73 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c  as a [SQLITE_ROL
1d1d0 4c 42 41 43 4b 20 7c 20 72 65 74 75 72 6e 20 63  LBACK | return c
1d1e0 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ode].** from the
1d1f0 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f   [sqlite3_vtab_o
1d200 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e  n_conflict()] in
1d210 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66  terface..*/.#def
1d220 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20  ine SQLITE_DENY 
1d230 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74    1   /* Abort t
1d240 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1d250 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a   with an error *
1d260 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1d270 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44  _IGNORE 2   /* D
1d280 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73  on't allow acces
1d290 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e  s, but don't gen
1d2a0 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a  erate an error *
1d2b0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
1d2c0 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63  F: Authorizer Ac
1d2d0 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  tion Codes.**.**
1d2e0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
1d2f0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
1d300 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
1d310 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
1d320 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  unction.** that 
1d330 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75  is invoked to au
1d340 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20  thorize certain 
1d350 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
1d360 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
1d370 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1d380 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1d390 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
1d3a0 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
1d3b0 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
1d3c0 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
1d3d0 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
1d3e0 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
1d3f0 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
1d400 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
1d410 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
1d420 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
1d430 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
1d440 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
1d450 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
1d460 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a  ration is to be.
1d470 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
1d480 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
1d490 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
1d4a0 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
1d4b0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
1d4c0 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
1d4d0 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
1d4e0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
1d4f0 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
1d500 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
1d510 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1d520 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68  eter.  ^(The 5th
1d530 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1d540 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
1d550 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
1d560 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
1d570 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74  base ("main", "t
1d580 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69  emp",.** etc.) i
1d590 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20  f applicable.)^ 
1d5a0 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65   ^The 6th parame
1d5b0 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
1d5c0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
1d5d0 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
1d5e0 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
1d5f0 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
1d600 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
1d610 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ble for.** the a
1d620 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
1d630 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
1d640 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
1d650 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
1d660 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
1d670 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ode..*/./*******
1d680 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1d690 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1d6a0 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a  **** 3rd *******
1d6b0 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a  ***** 4th ******
1d6c0 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  *****/.#define S
1d6d0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
1d6e0 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
1d6f0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1d700 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1d710 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1d720 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
1d730 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
1d740 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1d750 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1d760 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1d770 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1d780 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
1d790 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1d7a0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1d7b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1d7c0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
1d7d0 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
1d7e0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1d7f0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1d800 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1d810 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
1d820 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
1d830 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1d840 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1d850 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1d860 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
1d870 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
1d880 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1d890 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1d8a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d8b0 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
1d8c0 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
1d8d0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1d8e0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1d8f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1d900 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
1d910 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
1d920 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1d930 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1d940 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1d950 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
1d960 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
1d970 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1d980 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1d990 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1d9a0 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
1d9b0 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
1d9c0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1d9d0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1d9e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1d9f0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
1da00 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
1da10 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1da20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1da30 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1da40 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
1da50 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
1da60 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1da70 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1da80 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1da90 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
1daa0 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
1dab0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1dac0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1dad0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1dae0 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
1daf0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1db00 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1db10 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1db20 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1db30 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
1db40 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1db50 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1db60 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1db70 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
1db80 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
1db90 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1dba0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1dbb0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1dbc0 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
1dbd0 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
1dbe0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1dbf0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1dc00 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1dc10 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
1dc20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
1dc30 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1dc40 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1dc50 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1dc60 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
1dc70 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
1dc80 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
1dc90 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
1dca0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1dcb0 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
1dcc0 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
1dcd0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1dce0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
1dcf0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1dd00 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
1dd10 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
1dd20 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
1dd30 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1dd40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1dd50 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
1dd60 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70        22   /* Op
1dd70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55  eration       NU
1dd80 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1dd90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1dda0 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
1ddb0 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
1ddc0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
1ddd0 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
1dde0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1ddf0 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
1de00 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
1de10 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
1de20 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1de30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1de40 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
1de50 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
1de60 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
1de70 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1de80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54  efine SQLITE_ALT
1de90 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  ER_TABLE        
1dea0 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61    26   /* Databa
1deb0 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20  se Name   Table 
1dec0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1ded0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e  fine SQLITE_REIN
1dee0 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20  DEX             
1def0 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   27   /* Index N
1df00 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1df10 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1df20 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59  ine SQLITE_ANALY
1df30 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
1df40 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  28   /* Table Na
1df50 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1df60 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1df70 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1df80 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32  _VTABLE        2
1df90 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
1dfa0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
1dfb0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1dfc0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54  e SQLITE_DROP_VT
1dfd0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30  ABLE          30
1dfe0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1dff0 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
1e000 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1e010 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e   SQLITE_FUNCTION
1e020 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20               31 
1e030 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
1e040 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61       Function Na
1e050 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  me   */.#define 
1e060 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54  SQLITE_SAVEPOINT
1e070 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20              32  
1e080 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
1e090 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61      Savepoint Na
1e0a0 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  me  */.#define S
1e0b0 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20  QLITE_COPY      
1e0c0 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20              0   
1e0d0 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
1e0e0 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
1e0f0 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
1e100 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
1e110 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
1e120 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73  e routines regis
1e130 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
1e140 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20  ctions that can 
1e150 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  be used for.** t
1e160 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69  racing and profi
1e170 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ling the executi
1e180 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  on of SQL statem
1e190 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
1e1a0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1e1b0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
1e1c0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1e1d0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a   is invoked at.*
1e1e0 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20  * various times 
1e1f0 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  when an SQL stat
1e200 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72  ement is being r
1e210 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  un by [sqlite3_s
1e220 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20  tep()]..** ^The 
1e230 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
1e240 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1e250 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38  ked with a UTF-8
1e260 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
1e270 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  e.** SQL stateme
1e280 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73  nt text as the s
1e290 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
1e2a0 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e  egins executing.
1e2b0 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c  .** ^(Additional
1e2c0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1e2d0 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74   callbacks might
1e2e0 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63   occur.** as eac
1e2f0 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70  h triggered subp
1e300 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65  rogram is entere
1e310 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  d.  The callback
1e320 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a  s for triggers.*
1e330 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d  * contain a UTF-
1e340 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68  8 SQL comment th
1e350 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68  at identifies th
1e360 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a  e trigger.)^.**.
1e370 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
1e380 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1e390 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1e3a0 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76  profile() is inv
1e3b0 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20  oked.** as each 
1e3c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
1e3d0 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72  nishes.  ^The pr
1e3e0 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63  ofile callback c
1e3f0 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f  ontains.** the o
1e400 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
1e410 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73  t text and an es
1e420 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63  timate of wall-c
1e430 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20  lock time.** of 
1e440 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74  how long that st
1e450 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
1e460 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  run.  ^The profi
1e470 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  le callback.** t
1e480 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20  ime is in units 
1e490 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20  of nanoseconds, 
1e4a0 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72  however the curr
1e4b0 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
1e4c0 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61  on.** is only ca
1e4d0 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65  pable of millise
1e4e0 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20  cond resolution 
1e4f0 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74  so the six least
1e500 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20   significant.** 
1e510 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69  digits in the ti
1e520 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65  me are meaningle
1e530 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ss.  Future vers
1e540 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a  ions of SQLite.*
1e550 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20  * might provide 
1e560 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69  greater resoluti
1e570 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c  on on the profil
1e580 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68  er callback.  Th
1e590 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f  e.** sqlite3_pro
1e5a0 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  file() function 
1e5b0 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78  is considered ex
1e5c0 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69  perimental and i
1e5d0 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20  s.** subject to 
1e5e0 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
1e5f0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
1e600 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ite..*/.void *sq
1e610 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
1e620 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61  te3*, void(*xTra
1e630 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  ce)(void*,const 
1e640 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  char*), void*);.
1e650 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
1e660 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  TAL void *sqlite
1e670 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
1e680 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
1e690 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
1e6a0 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
1e6b0 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
1e6c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1e6d0 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73  F: Query Progres
1e6e0 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  s Callbacks.**.*
1e6f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70  * ^The sqlite3_p
1e700 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
1e710 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61  D,N,X,P) interfa
1e720 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61  ce causes the ca
1e730 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
1e740 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on X to be invok
1e750 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
1e760 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e  during long runn
1e770 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ing calls to.** 
1e780 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1e790 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
1e7a0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1e7b0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72  get_table()] for
1e7c0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1e7d0 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65  nection D.  An e
1e7e0 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74  xample use for t
1e7f0 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  his.** interface
1e800 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55   is to keep a GU
1e810 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67  I updated during
1e820 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a   a large query..
1e830 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d  **.** ^The param
1e840 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64  eter P is passed
1e850 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
1e860 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
1e870 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61  o the .** callba
1e880 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20  ck function X.  
1e890 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e  ^The parameter N
1e8a0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
1e8b0 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d  f .** [virtual m
1e8c0 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69  achine instructi
1e8d0 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76  ons] that are ev
1e8e0 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20  aluated between 
1e8f0 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e  successive.** in
1e900 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
1e910 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a   callback X..**.
1e920 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  ** ^Only a singl
1e930 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1e940 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65  er may be define
1e950 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65  d at one time pe
1e960 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1e970 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74  onnection]; sett
1e980 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65  ing a new progre
1e990 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65  ss handler cance
1e9a0 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e  ls the.** old on
1e9b0 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72  e.  ^Setting par
1e9c0 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c  ameter X to NULL
1e9d0 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72   disables the pr
1e9e0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
1e9f0 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73  ** ^The progress
1ea00 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f   handler is also
1ea10 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74   disabled by set
1ea20 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75  ting N to a valu
1ea30 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31  e less.** than 1
1ea40 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1ea50 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
1ea60 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
1ea70 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ro, the operatio
1ea80 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70  n is.** interrup
1ea90 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75  ted.  This featu
1eaa0 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  re can be used t
1eab0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a  o implement a.**
1eac0 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e   "Cancel" button
1ead0 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65   on a GUI progre
1eae0 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a  ss dialog box..*
1eaf0 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73  *.** The progres
1eb00 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  s handler callba
1eb10 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
1eb20 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
1eb30 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
1eb40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1eb50 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
1eb60 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
1eb70 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74  ndler..** Note t
1eb80 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
1eb90 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
1eba0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1ebb0 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
1ebc0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
1ebd0 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
1ebe0 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
1ebf0 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
1ec00 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76  ragraph..**.*/.v
1ec10 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  oid sqlite3_prog
1ec20 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c  ress_handler(sql
1ec30 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28  ite3*, int, int(
1ec40 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
1ec50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1ec60 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65  EF: Opening A Ne
1ec70 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  w Database Conne
1ec80 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
1ec90 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e  se routines open
1eca0 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62   an SQLite datab
1ecb0 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63  ase file as spec
1ecc0 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
1ecd0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1ece0 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d  nt. ^The filenam
1ecf0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
1ed00 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
1ed10 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
1ed20 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
1ed30 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
1ed40 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
1ed50 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
1ed60 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
1ed70 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e  ite3_open16(). ^
1ed80 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  (A [database con
1ed90 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
1eda0 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65  is usually.** re
1edb0 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c  turned in *ppDb,
1edc0 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f   even if an erro
1edd0 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f  r occurs.  The o
1ede0 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73  nly exception is
1edf0 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69   that.** if SQLi
1ee00 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
1ee10 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
1ee20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c  to hold the [sql
1ee30 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a  ite3] object,.**
1ee40 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20   a NULL will be 
1ee50 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70  written into *pp
1ee60 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  Db instead of a 
1ee70 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
1ee80 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65  sqlite3].** obje
1ee90 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64  ct.)^ ^(If the d
1eea0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1eeb0 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65  d (and/or create
1eec0 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  d) successfully,
1eed0 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45   then.** [SQLITE
1eee0 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
1eef0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
1ef00 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
1ef10 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65  returned.)^ ^The
1ef20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
1ef30 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
1ef40 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
1ef50 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
1ef60 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
1ef70 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
1ef80 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
1ef90 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f   of the error fo
1efa0 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72  llowing a failur
1efb0 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  e of any.** of t
1efc0 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  he sqlite3_open(
1efd0 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  ) routines..**.*
1efe0 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65  * ^The default e
1eff0 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20  ncoding for the 
1f000 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1f010 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c   UTF-8 if.** sql
1f020 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
1f030 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1f040 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a   is called and.*
1f050 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  * UTF-16 in the 
1f060 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1f070 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  r if sqlite3_ope
1f080 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a  n16() is used..*
1f090 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
1f0a0 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
1f0b0 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
1f0c0 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
1f0d0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
1f0e0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
1f0f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
1f100 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
1f110 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61  eleased by.** pa
1f120 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
1f130 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
1f140 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
1f150 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
1f160 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
1f170 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  pen_v2() interfa
1f180 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  ce works like sq
1f190 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
1f1a0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
1f1b0 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
1f1c0 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
1f1d0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
1f1e0 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
1f1f0 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
1f200 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28   connection.  ^(
1f210 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
1f220 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ter to.** sqlite
1f230 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20  3_open_v2() can 
1f240 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
1f250 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
1f260 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
1f270 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
1f280 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
1f290 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
1f2a0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
1f2b0 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  FULLMUTEX], [SQL
1f2c0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
1f2d0 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ACHE],.** [SQLIT
1f2e0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
1f2f0 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51  CHE], and/or [SQ
1f300 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
1f310 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64  lags:)^.**.** <d
1f320 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  l>.** ^(<dt>[SQL
1f330 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
1f340 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
1f350 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1f360 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
1f370 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
1f380 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
1f390 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
1f3a0 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
1f3b0 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
1f3c0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
1f3d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1f3e0 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RITE]</dt>.** <d
1f3f0 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1f400 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
1f410 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
1f420 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
1f430 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79   reading.** only
1f440 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
1f450 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
1f460 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
1f470 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74   system.  In eit
1f480 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  her.** case the 
1f490 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
1f4a0 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68  ready exist, oth
1f4b0 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
1f4c0 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
1f4d0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1f4e0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1f4f0 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
1f500 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f  E_OPEN_CREATE]</
1f510 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
1f520 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1f530 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
1f540 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69  d writing, and i
1f550 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20  s created if.** 
1f560 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
1f570 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
1f580 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
1f590 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
1f5a0 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
1f5b0 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
1f5c0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
1f5d0 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
1f5e0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
1f5f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1f600 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1f610 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
1f620 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  e.** combination
1f630 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70  s shown above op
1f640 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
1f650 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20  d with other.** 
1f660 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1f670 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f  DONLY | SQLITE_O
1f680 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74  PEN_* bits].** t
1f690 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1f6a0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
1f6b0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51  *.** ^If the [SQ
1f6c0 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1f6d0 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20  X] flag is set, 
1f6e0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
1f6f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1f700 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c  opens in the mul
1f710 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
1f720 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f  ding mode] as lo
1f730 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65  ng as the single
1f740 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20  -thread.** mode 
1f750 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74  has not been set
1f760 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
1f770 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20   or start-time. 
1f780 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
1f790 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
1f7a0 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  EX] flag is set 
1f7b0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
1f7c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
1f7d0 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72  ns.** in the ser
1f7e0 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
1f7f0 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20  ng mode] unless 
1f800 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61  single-thread wa
1f810 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  s.** previously 
1f820 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70  selected at comp
1f830 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
1f840 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  t-time..** ^The 
1f850 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
1f860 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63  REDCACHE] flag c
1f870 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
1f880 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
1f890 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20   be.** eligible 
1f8a0 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63  to use [shared c
1f8b0 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61  ache mode], rega
1f8c0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
1f8d0 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a  r or not shared.
1f8e0 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ** cache is enab
1f8f0 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  led using [sqlit
1f900 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
1f910 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65  _cache()].  ^The
1f920 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1f930 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66  _PRIVATECACHE] f
1f940 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
1f950 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1f960 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72  on to not.** par
1f970 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61  ticipate in [sha
1f980 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20  red cache mode] 
1f990 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e  even if it is en
1f9a0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
1f9b0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1f9c0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
1f9d0 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e  en_v2() is the n
1f9e0 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ame of the.** [s
1f9f0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1fa00 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
1fa10 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
1fa20 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
1fa30 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64  hat.** the new d
1fa40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1fa50 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20  on should use.  
1fa60 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
1fa70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61  arameter is.** a
1fa80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
1fa90 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  en the default [
1faa0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1fab0 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ect is used..**.
1fac0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
1fad0 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ame is ":memory:
1fae0 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  ", then a privat
1faf0 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d  e, temporary in-
1fb00 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a  memory database.
1fb10 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  ** is created fo
1fb20 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
1fb30 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  .  ^This in-memo
1fb40 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ry database will
1fb50 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20   vanish when.** 
1fb60 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1fb70 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
1fb80 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  d.  Future versi
1fb90 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
1fba0 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20  ght.** make use 
1fbb0 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
1fbc0 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20  ecial filenames 
1fbd0 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
1fbe0 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
1fbf0 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f  r..** It is reco
1fc00 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65  mmended that whe
1fc10 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
1fc20 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64  ename actually d
1fc30 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
1fc40 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65  * a ":" characte
1fc50 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65  r you should pre
1fc60 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  fix the filename
1fc70 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65   with a pathname
1fc80 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22   such as.** "./"
1fc90 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75   to avoid ambigu
1fca0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ity..**.** ^If t
1fcb0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
1fcc0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
1fcd0 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
1fce0 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
1fcf0 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
1fd00 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
1fd10 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61  ^This private da
1fd20 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a  tabase will be.*
1fd30 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
1fd40 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20  deleted as soon 
1fd50 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
1fd60 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
1fd70 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  osed..**.** [[UR
1fd80 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73  I filenames in s
1fd90 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20  qlite3_open()]] 
1fda0 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65  <h3>URI Filename
1fdb0 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66  s</h3>.**.** ^If
1fdc0 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20   [URI filename] 
1fdd0 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
1fde0 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74  s enabled, and t
1fdf0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
1fe00 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77  ment.** begins w
1fe10 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65  ith "file:", the
1fe20 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  n the filename i
1fe30 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
1fe40 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20   a URI. ^URI.** 
1fe50 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
1fe60 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
1fe70 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ed if the [SQLIT
1fe80 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
1fe90 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68   is.** set in th
1fea0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
1feb0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
1fec0 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74  n_v2(), or if it
1fed0 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61   has.** been ena
1fee0 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73  bled globally us
1fef0 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
1ff00 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69  CONFIG_URI] opti
1ff10 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  on with the.** [
1ff20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
1ff30 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74  ] method or by t
1ff40 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  he [SQLITE_USE_U
1ff50 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  RI] compile-time
1ff60 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f   option..** As o
1ff70 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
1ff80 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65   3.7.7, URI file
1ff90 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
1ffa0 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66  ion is turned of
1ffb0 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c  f.** by default,
1ffc0 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65   but future rele
1ffd0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ases of SQLite m
1ffe0 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20  ight enable URI 
1fff0 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65  filename.** inte
20000 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65  rpretation by de
20010 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52  fault.  See "[UR
20020 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f  I filenames]" fo
20030 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
20040 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
20050 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  ** URI filenames
20060 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f   are parsed acco
20070 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38  rding to RFC 398
20080 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63  6. ^If the URI c
20090 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75  ontains an.** au
200a0 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74  thority, then it
200b0 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
200c0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
200d0 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a  or the string .*
200e0 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e  * "localhost". ^
200f0 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  If the authority
20100 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79   is not an empty
20110 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61   string or "loca
20120 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65  lhost", an .** e
20130 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
20140 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20   to the caller. 
20150 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f  ^The fragment co
20160 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
20170 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74  , if .** present
20180 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  , is ignored..**
20190 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
201a0 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e   the path compon
201b0 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61  ent of the URI a
201c0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
201d0 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77  e disk file.** w
201e0 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68  hich contains th
201f0 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20  e database. ^If 
20200 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20  the path begins 
20210 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61  with a '/' chara
20220 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69  cter, .** then i
20230 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
20240 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   as an absolute 
20250 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61  path. ^If the pa
20260 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69  th does not begi
20270 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27  n .** with a '/'
20280 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74   (meaning that t
20290 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63  he authority sec
202a0 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20  tion is omitted 
202b0 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a  from the URI).**
202c0 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69   then the path i
202d0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
202e0 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68   a relative path
202f0 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77  . .** ^On window
20300 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d  s, the first com
20310 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73  ponent of an abs
20320 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69  olute path .** i
20330 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66  s a drive specif
20340 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43  ication (e.g. "C
20350 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72  :")..**.** [[cor
20360 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61  e URI query para
20370 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20  meters]].** The 
20380 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
20390 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e  of a URI may con
203a0 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tain parameters 
203b0 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72  that are interpr
203c0 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62  eted.** either b
203d0 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c  y SQLite itself,
203e0 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20   or by a [VFS | 
203f0 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65  custom VFS imple
20400 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53  mentation]..** S
20410 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73  QLite interprets
20420 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
20430 68 72 65 65 20 71 75 65 72 79 20 70 61 72 61 6d  hree query param
20440 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  eters:.**.** <ul
20450 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76  >.**   <li> <b>v
20460 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66  fs</b>: ^The "vf
20470 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  s" parameter may
20480 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63   be used to spec
20490 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a  ify the name of.
204a0 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a  **     a VFS obj
204b0 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65  ect that provide
204c0 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
204d0 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
204e0 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20   that should.** 
204f0 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61      be used to a
20500 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
20510 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e  se file on disk.
20520 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e   ^If this option
20530 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20   is set to.**   
20540 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e    an empty strin
20550 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  g the default VF
20560 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  S object is used
20570 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  . ^Specifying an
20580 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20   unknown.**     
20590 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e  VFS is an error.
205a0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
205b0 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
205c0 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f  nd the vfs optio
205d0 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73  n is.**     pres
205e0 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46  ent, then the VF
205f0 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  S specified by t
20600 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  he option takes 
20610 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a  precedence over.
20620 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65  **     the value
20630 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
20640 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
20650 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
20660 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
20670 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20  i> <b>mode</b>: 
20680 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d  ^(The mode param
20690 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
206a0 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20  to either "ro", 
206b0 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77  "rw",.**     "rw
206c0 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e  c", or "memory".
206d0 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73   Attempting to s
206e0 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68  et it to any oth
206f0 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20  er value is.**  
20700 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a     an error)^. .
20710 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20  **     ^If "ro" 
20720 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68  is specified, th
20730 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
20740 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
20750 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20  ad-only .**     
20760 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20  access, just as 
20770 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
20780 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c  PEN_READONLY] fl
20790 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20  ag had been set 
207a0 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74  in the .**     t
207b0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
207c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
207d0 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  (). ^If the mode
207e0 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
207f0 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20  o .**     "rw", 
20800 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
20810 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
20820 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20  read-write (but 
20830 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20  not create) .** 
20840 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69      access, as i
20850 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  f SQLITE_OPEN_RE
20860 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74  ADWRITE (but not
20870 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
20880 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20  ATE) had .**    
20890 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75   been set. ^Valu
208a0 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76  e "rwc" is equiv
208b0 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
208c0 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51   both .**     SQ
208d0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
208e0 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f  ITE and SQLITE_O
208f0 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66  PEN_CREATE.  ^If
20900 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
20910 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74   is.**     set t
20920 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20  o "memory" then 
20930 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72  a pure [in-memor
20940 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74  y database] that
20950 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20   never reads.** 
20960 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72      or writes fr
20970 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e  om disk is used.
20980 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72   ^It is an error
20990 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61   to specify a va
209a0 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74  lue for.**     t
209b0 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
209c0 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72  r that is less r
209d0 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20  estrictive than 
209e0 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62  that specified b
209f0 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61  y.**     the fla
20a00 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65  gs passed in the
20a10 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
20a20 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
20a30 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
20a40 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e  li> <b>cache</b>
20a50 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72  : ^The cache par
20a60 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
20a70 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61  t to either "sha
20a80 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22  red" or.**     "
20a90 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69  private". ^Setti
20aa0 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64  ng it to "shared
20ab0 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
20ac0 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a  to setting the.*
20ad0 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
20ae0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69  N_SHAREDCACHE bi
20af0 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61  t in the flags a
20b00 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74  rgument passed t
20b10 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33  o.**     sqlite3
20b20 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74  _open_v2(). ^Set
20b30 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70  ting the cache p
20b40 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69  arameter to "pri
20b50 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20  vate" is .**    
20b60 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
20b70 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54  etting the SQLIT
20b80 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
20b90 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20  CHE bit..**     
20ba0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
20bb0 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
20bc0 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61  d the "cache" pa
20bd0 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65  rameter is prese
20be0 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55  nt in.**     a U
20bf0 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73  RI filename, its
20c00 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73   value overrides
20c10 20 61 6e 79 20 62 65 68 61 76 69 6f 75 72 20 72   any behaviour r
20c20 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74  equested by sett
20c30 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  ing.**     SQLIT
20c40 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
20c50 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50  CHE or SQLITE_OP
20c60 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66  EN_SHAREDCACHE f
20c70 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  lag..** </ul>.**
20c80 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20  .** ^Specifying 
20c90 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d  an unknown param
20ca0 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72  eter in the quer
20cb0 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
20cc0 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a   URI is not an.*
20cd0 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65  * error.  Future
20ce0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
20cf0 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73  ite might unders
20d00 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20  tand additional 
20d10 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
20d20 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72  ers.  See "[quer
20d30 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74  y parameters wit
20d40 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e  h special meanin
20d50 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f  g to SQLite]" fo
20d60 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
20d70 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
20d80 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
20d90 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33  e examples]] <h3
20da0 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  >URI filename ex
20db0 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  amples</h3>.**.*
20dc0 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
20dd0 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72  "1" align=center
20de0 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a   cellpadding=5>.
20df0 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20  ** <tr><th> URI 
20e00 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52  filenames <th> R
20e10 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74  esults.** <tr><t
20e20 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20  d> file:data.db 
20e30 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
20e40 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20    Open the file 
20e50 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
20e60 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
20e70 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ry..** <tr><td> 
20e80 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
20e90 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20  data.db<br>.**  
20ea0 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
20eb0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
20ec0 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20  b <br> .**      
20ed0 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c      file://local
20ee0 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  host/home/fred/d
20ef0 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e  ata.db <br> <td>
20f00 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
20f10 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
20f20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
20f30 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74  /data.db"..** <t
20f40 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61  r><td> file://da
20f50 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64  rkstar/home/fred
20f60 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  /data.db <td> .*
20f70 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
20f80 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20  ror. "darkstar" 
20f90 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69  is not a recogni
20fa0 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a  zed authority..*
20fb0 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d  * <tr><td style=
20fc0 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77  "white-space:now
20fd0 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20  rap"> .**       
20fe0 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f     file:///C:/Do
20ff0 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30  cuments%20and%20
21000 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65  Settings/fred/De
21010 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a  sktop/data.db.**
21020 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77       <td> Window
21030 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65  s only: Open the
21040 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
21050 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f  on fred's deskto
21060 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20  p on drive.**   
21070 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20         C:. Note 
21080 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63  that the %20 esc
21090 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78  aping in this ex
210a0 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72  ample is not str
210b0 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20  ictly .**       
210c0 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73     necessary - s
210d0 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20  pace characters 
210e0 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65  can be used lite
210f0 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  rally.**        
21100 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d    in URI filenam
21110 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  es..** <tr><td> 
21120 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
21130 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61  e=ro&cache=priva
21140 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  te <td> .**     
21150 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
21160 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
21170 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
21180 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  y for read-only 
21190 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20  access..**      
211a0 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f      Regardless o
211b0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
211c0 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f   shared-cache mo
211d0 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79  de is enabled by
211e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66  .**          def
211f0 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76  ault, use a priv
21200 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74  ate cache..** <t
21210 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
21220 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76  e/fred/data.db?v
21230 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c  fs=unix-nolock <
21240 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  td>.**          
21250 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65  Open file "/home
21260 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20  /fred/data.db". 
21270 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20  Use the special 
21280 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b  VFS "unix-nolock
21290 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  "..** <tr><td> f
212a0 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
212b0 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a  =readonly <td> .
212c0 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
212d0 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22  rror. "readonly"
212e0 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20   is not a valid 
212f0 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22  option for the "
21300 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e  mode" parameter.
21310 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a  .** </table>.**.
21320 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69  ** ^URI hexadeci
21330 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
21340 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73  nces (%HH) are s
21350 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20  upported within 
21360 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20  the path and.** 
21370 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
21380 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78   of a URI. A hex
21390 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
213a0 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74  sequence consist
213b0 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e  s of a.** percen
213c0 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66  t sign - "%" - f
213d0 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74  ollowed by exact
213e0 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d  ly two hexadecim
213f0 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70  al digits .** sp
21400 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65  ecifying an octe
21410 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65  t value. ^Before
21420 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65   the path or que
21430 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
21440 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61   a.** URI filena
21450 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  me are interpret
21460 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63  ed, they are enc
21470 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
21480 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78   and all .** hex
21490 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
214a0 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63  sequences replac
214b0 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62  ed by a single b
214c0 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  yte containing t
214d0 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64  he.** correspond
214e0 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68  ing octet. If th
214f0 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72  is process gener
21500 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20  ates an invalid 
21510 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a  UTF-8 encoding,.
21520 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ** the results a
21530 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
21540 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
21550 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
21560 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
21570 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
21580 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
21590 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
215a0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
215b0 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
215c0 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
215d0 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
215e0 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
215f0 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
21600 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
21610 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
21620 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
21630 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
21640 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
21650 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
21660 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
21670 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
21680 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62  n_v2()..**.** <b
21690 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
216a0 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c   Runtime users:<
216b0 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61  /b>  The tempora
216c0 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73  ry directory mus
216d0 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f  t be set.** prio
216e0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c  r to calling sql
216f0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
21700 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
21710 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61  .  Otherwise, va
21720 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65  rious.** feature
21730 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74  s that require t
21740 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72  he use of tempor
21750 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61  ary files may fa
21760 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  il..**.** See al
21770 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d  so: [sqlite3_tem
21780 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a  p_directory].*/.
21790 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
217a0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
217b0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
217c0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
217d0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
217e0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
217f0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
21800 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
21810 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
21820 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
21830 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
21840 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
21850 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
21860 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
21870 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
21880 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
21890 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
218a0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
218b0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
218c0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
218d0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
218e0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
218f0 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
21900 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
21910 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
21920 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
21930 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
21940 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
21950 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
21960 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
21970 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
21980 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
21990 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c  3REF: Obtain Val
219a0 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61  ues For URI Para
219b0 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  meters.**.** The
219c0 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72  se are utility r
219d0 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20  outines, useful 
219e0 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
219f0 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
21a00 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ck.** to see if 
21a10 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
21a20 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63  was a URI that c
21a30 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69  ontained a speci
21a40 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61  fic query .** pa
21a50 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20  rameter, and if 
21a60 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76  so obtains the v
21a70 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65  alue of that que
21a80 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
21a90 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20  .** If F is the 
21aa0 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
21ab0 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  e pointer passed
21ac0 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28   into the xOpen(
21ad0 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20  ) method of .** 
21ae0 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  a VFS implementa
21af0 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c  tion when the fl
21b00 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
21b10 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65   xOpen() has one
21b20 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20   or .** more of 
21b30 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
21b40 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _URI] or [SQLITE
21b50 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62  _OPEN_MAIN_DB] b
21b60 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50  its set and.** P
21b70 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
21b80 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  the query parame
21b90 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  ter, then.** sql
21ba0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
21bb0 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
21bc0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
21bd0 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20   P.** parameter 
21be0 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20  if it exists or 
21bf0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
21c00 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70  f P does not app
21c10 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65  ear as a .** que
21c20 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ry parameter on 
21c30 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75  F.  If P is a qu
21c40 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66  ery parameter of
21c50 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70   F.** has no exp
21c60 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65  licit value, the
21c70 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
21c80 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
21c90 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  urns.** a pointe
21ca0 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  r to an empty st
21cb0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
21cc0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
21cd0 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
21ce0 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ne assumes that 
21cf0 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a  P is a boolean.*
21d00 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  * parameter and 
21d10 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
21d20 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63   or false (0) ac
21d30 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76  cording to the v
21d40 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54  alue.** of P.  T
21d50 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
21d60 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
21d70 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72  utine returns tr
21d80 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a  ue (1) if the.**
21d90 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20   value of query 
21da0 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
21db0 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72  ne of "yes", "tr
21dc0 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20  ue", or "on" in 
21dd0 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69  any.** case or i
21de0 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
21df0 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  ns with a non-ze
21e00 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  ro number.  The 
21e10 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
21e20 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
21e30 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20  outines returns 
21e40 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65  false (0) if the
21e50 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65   value of.** que
21e60 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
21e70 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22  s one of "no", "
21e80 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22  false", or "off"
21e90 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a   in any case or.
21ea0 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ** if the value 
21eb0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75  begins with a nu
21ec0 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20  meric zero.  If 
21ed0 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79  P is not a query
21ee0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  .** parameter on
21ef0 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c   F or if the val
21f00 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20  ue of P is does 
21f10 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66  not match any of
21f20 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74   the.** above, t
21f30 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
21f40 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
21f50 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a  eturns (B!=0)..*
21f60 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
21f70 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44  _uri_int64(F,P,D
21f80 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72  ) routine conver
21f90 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ts the value of 
21fa0 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62  P into a.** 64-b
21fb0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
21fc0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68  r and returns th
21fd0 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44  at integer, or D
21fe0 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a   if P does not.*
21ff0 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65  * exist.  If the
22000 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73   value of P is s
22010 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
22020 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20  han an integer, 
22030 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20  then.** zero is 
22040 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a  returned..** .**
22050 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20   If F is a NULL 
22060 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71  pointer, then sq
22070 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
22080 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
22090 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c   NULL and.** sql
220a0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
220b0 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
220c0 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20  B.  If F is not 
220d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
220e0 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64  nd.** is not a d
220f0 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74  atabase file pat
22100 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68  hname pointer th
22110 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64  at SQLite passed
22120 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a   into the xOpen.
22130 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74  ** VFS method, t
22140 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
22150 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
22160 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
22170 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e  d probably.** un
22180 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f  desirable..*/.co
22190 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
221a0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
221b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
221c0 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61  ename, const cha
221d0 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20  r *zParam);.int 
221e0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
221f0 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ean(const char *
22200 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61  zFile, const cha
22210 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62  r *zParam, int b
22220 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65  Default);.sqlite
22230 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
22240 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20  uri_int64(const 
22250 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61  char*, const cha
22260 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
22270 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  4);.../*.** CAPI
22280 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
22290 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a  s And Messages.*
222a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
222b0 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
222c0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
222d0 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
222e0 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  t code] or.** [e
222f0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
22300 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
22310 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
22320 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
22330 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ll.** associated
22340 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
22350 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49  e connection]. I
22360 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
22370 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74  ll failed.** but
22380 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
22390 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
223a0 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
223b0 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71  value from.** sq
223c0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
223d0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e  is undefined.  ^
223e0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
223f0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
22400 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
22410 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
22420 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
22430 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
22440 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
22450 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
22460 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
22470 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
22480 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
22490 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
224a0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
224b0 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
224c0 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
224d0 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
224e0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
224f0 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
22500 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
22510 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
22520 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
22530 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
22540 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
22550 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
22560 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
22570 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
22580 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
22590 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
225a0 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
225b0 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
225c0 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
225d0 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
225e0 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
225f0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
22600 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
22610 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
22620 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
22630 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e  ite3_errstr() in
22640 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
22650 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  the English-lang
22660 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61  uage text.** tha
22670 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
22680 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61  [result code], a
22690 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65  s UTF-8..** ^(Me
226a0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
226b0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
226c0 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
226d0 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61   internally.** a
226e0 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66  nd must not be f
226f0 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  reed by the appl
22700 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a  ication)^..**.**
22710 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
22720 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
22730 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
22740 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
22750 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
22760 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
22770 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
22780 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
22790 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
227a0 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
227b0 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
227c0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
227d0 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
227e0 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
227f0 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
22800 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
22810 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
22820 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
22830 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
22840 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
22850 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
22860 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
22870 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
22880 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
22890 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
228a0 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
228b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
228c0 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
228d0 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
228e0 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
228f0 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
22900 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
22910 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
22920 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
22930 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
22940 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
22950 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
22960 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
22970 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
22980 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
22990 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
229a0 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
229b0 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
229c0 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
229d0 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
229e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
229f0 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
22a00 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
22a10 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
22a20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
22a30 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
22a40 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  3_errcode(sqlite
22a50 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69  3 *db);.int sqli
22a60 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
22a70 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
22a80 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
22a90 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
22aa0 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76  lite3*);.const v
22ab0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
22ac0 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
22ad0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
22ae0 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29  ite3_errstr(int)
22af0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22b00 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  F: SQL Statement
22b10 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
22b20 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73  RDS: {prepared s
22b30 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61  tatement} {prepa
22b40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a  red statements}.
22b50 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
22b60 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
22b70 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69   represents a si
22b80 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
22b90 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  nt..** This obje
22ba0 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20  ct is variously 
22bb0 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70  known as a "prep
22bc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20  ared statement" 
22bd0 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65  or a.** "compile
22be0 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22  d SQL statement"
22bf0 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20   or simply as a 
22c00 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a  "statement"..**.
22c10 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61  ** The life of a
22c20 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
22c30 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67  t goes something
22c40 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
22c50 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
22c60 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74  reate the object
22c70 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
22c80 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
22c90 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20   a related.**   
22ca0 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20     function..** 
22cb0 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
22cc0 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65   to [host parame
22cd0 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20  ters] using the 
22ce0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
22cf0 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61  .**      interfa
22d00 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  ces..** <li> Run
22d10 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
22d20 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
22d30 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
22d40 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
22d50 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d  Reset the statem
22d60 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
22d70 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
22d80 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
22d90 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
22da0 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
22db0 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
22dc0 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
22dd0 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
22de0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
22df0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52  ** </ol>.**.** R
22e00 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74  efer to document
22e10 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
22e20 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  ual methods abov
22e30 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  e for additional
22e40 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
22e50 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
22e60 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
22e70 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
22e80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
22e90 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a  un-time Limits.*
22ea0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
22eb0 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65  rface allows the
22ec0 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73   size of various
22ed0 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
22ee0 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20  e limited.** on 
22ef0 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20  a connection by 
22f00 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
22f10 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
22f20 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
22f30 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
22f40 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d  ction] whose lim
22f50 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20  it is to be set 
22f60 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65  or queried.  The
22f70 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
22f80 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74  eter is one of t
22f90 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f  he [limit catego
22fa0 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e  ries] that defin
22fb0 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20  e a.** class of 
22fc0 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
22fd0 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20   size limited.  
22fe0 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
22ff0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65  ter is the.** ne
23000 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74  w limit for that
23010 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a   construct.)^.**
23020 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .** ^If the new 
23030 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
23040 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
23050 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
23060 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63  ed..** ^(For eac
23070 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  h limit category
23080 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69   SQLITE_LIMIT_<i
23090 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20  >NAME</i> there 
230a0 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
230b0 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
230c0 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63  und].** set at c
230d0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61  ompile-time by a
230e0 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
230f0 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20  macro called.** 
23100 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
23110 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  _MAX_<i>NAME</i>
23120 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
23130 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
23140 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
23150 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
23160 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
23170 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
23180 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
23190 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
231a0 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
231b0 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
231c0 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
231d0 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77  ^Regardless of w
231e0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
231f0 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e  e limit was chan
23200 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71  ged, the .** [sq
23210 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69  lite3_limit()] i
23220 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
23230 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
23240 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a   of the limit..*
23250 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e  * ^Hence, to fin
23260 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  d the current va
23270 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77  lue of a limit w
23280 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20  ithout changing 
23290 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e  it,.** simply in
232a0 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66  voke this interf
232b0 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69  ace with the thi
232c0 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74  rd parameter set
232d0 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75   to -1..**.** Ru
232e0 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n-time limits ar
232f0 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
23300 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
23310 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
23320 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
23330 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
23340 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
23350 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
23360 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
23370 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
23380 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
23390 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
233a0 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
233b0 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68  * web browser th
233c0 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
233d0 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
233e0 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
233f0 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
23400 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
23410 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
23420 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
23430 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
23440 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
23450 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
23460 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
23470 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
23480 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
23490 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
234a0 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
234b0 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
234c0 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
234d0 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
234e0 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
234f0 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
23500 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
23510 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
23520 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
23530 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
23540 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
23550 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
23560 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
23570 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
23580 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
23590 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
235a0 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
235b0 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
235c0 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
235d0 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
235e0 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
235f0 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75  A]..**.** New ru
23600 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74  n-time limit cat
23610 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61  egories may be a
23620 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
23630 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20  eleases..*/.int 
23640 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
23650 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
23660 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
23670 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
23680 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
23690 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f  egories.** KEYWO
236a0 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65  RDS: {limit cate
236b0 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61  gory} {*limit ca
236c0 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20  tegories}.**.** 
236d0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
236e0 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70  define various p
236f0 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74  erformance limit
23700 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
23710 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d   lowered at run-
23720 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  time using [sqli
23730 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
23740 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66   The synopsis of
23750 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   the meanings of
23760 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
23770 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c  its is shown bel
23780 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  ow..** Additiona
23790 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  l information is
237a0 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c   available at [l
237b0 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69  imits | Limits i
237c0 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a  n SQLite]..**.**
237d0 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
237e0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d  E_LIMIT_LENGTH]]
237f0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
23800 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  MIT_LENGTH</dt>.
23810 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
23820 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73  um size of any s
23830 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72  tring or BLOB or
23840 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62   table row, in b
23850 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a  ytes.<dd>)^.**.*
23860 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
23870 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  _SQL_LENGTH]] ^(
23880 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
23890 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  _SQL_LENGTH</dt>
238a0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
238b0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e  mum length of an
238c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
238d0 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e  in bytes.</dd>)^
238e0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
238f0 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e  LIMIT_COLUMN]] ^
23900 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
23910 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a  T_COLUMN</dt>.**
23920 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
23930 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
23940 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65  ns in a table de
23950 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74  finition or in t
23960 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74  he.** result set
23970 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f   of a [SELECT] o
23980 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  r the maximum nu
23990 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
239a0 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f  in an index.** o
239b0 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59  r in an ORDER BY
239c0 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61   or GROUP BY cla
239d0 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  use.</dd>)^.**.*
239e0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
239f0 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28  _EXPR_DEPTH]] ^(
23a00 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
23a10 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
23a20 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
23a30 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
23a40 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
23a50 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
23a60 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
23a70 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
23a80 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c  UND_SELECT]] ^(<
23a90 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
23aa0 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c  COMPOUND_SELECT<
23ab0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
23ac0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
23ad0 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d  f terms in a com
23ae0 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61  pound SELECT sta
23af0 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a  tement.</dd>)^.*
23b00 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
23b10 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28  MIT_VDBE_OP]] ^(
23b20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
23b30 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a  _VDBE_OP</dt>.**
23b40 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
23b50 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72   number of instr
23b60 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72  uctions in a vir
23b70 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f  tual machine pro
23b80 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20  gram.** used to 
23b90 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c  implement an SQL
23ba0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69   statement.  Thi
23bb0 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  s limit is not c
23bc0 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f  urrently.** enfo
23bd0 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61  rced, though tha
23be0 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64  t might be added
23bf0 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
23c00 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
23c10 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  Lite.</dd>)^.**.
23c20 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
23c30 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d  T_FUNCTION_ARG]]
23c40 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
23c50 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
23c60 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
23c70 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
23c80 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
23c90 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
23ca0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
23cb0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
23cc0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
23cd0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f  LIMIT_ATTACHED</
23ce0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
23cf0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
23d00 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63   [ATTACH | attac
23d10 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29  hed databases].)
23d20 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ^</dd>.**.** [[S
23d30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
23d40 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d  _PATTERN_LENGTH]
23d50 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
23d60 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
23d70 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
23d80 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
23d90 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
23da0 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
23db0 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d  nt to the [LIKE]
23dc0 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70   or.** [GLOB] op
23dd0 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a  erators.</dd>)^.
23de0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
23df0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
23e00 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  MBER]].** ^(<dt>
23e10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
23e20 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
23e30 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
23e40 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65  imum index numbe
23e50 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65  r of any [parame
23e60 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73  ter] in an SQL s
23e70 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a  tatement.)^.**.*
23e80 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
23e90 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d  _TRIGGER_DEPTH]]
23ea0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
23eb0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
23ec0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
23ed0 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
23ee0 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72  of recursion for
23ef0 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29   triggers.</dd>)
23f00 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ^.** </dl>.*/.#d
23f10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
23f20 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  IT_LENGTH       
23f30 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23               0.#
23f40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
23f50 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20  MIT_SQL_LENGTH  
23f60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
23f70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
23f80 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20  IMIT_COLUMN     
23f90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
23fa0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23fb0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
23fc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23fd0 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
23fe0 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
23ff0 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
24000 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
24010 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20  E_LIMIT_VDBE_OP 
24020 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24030 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
24040 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
24050 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20  N_ARG           
24060 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
24070 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
24080 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
24090 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
240a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
240b0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20  PATTERN_LENGTH  
240c0 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
240d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
240e0 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20  ABLE_NUMBER     
240f0 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
24100 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
24110 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20  GGER_DEPTH      
24120 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20        10../*.** 
24130 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
24140 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ing An SQL State
24150 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ment.** KEYWORDS
24160 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  : {SQL statement
24170 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a   compiler}.**.**
24180 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53   To execute an S
24190 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73  QL query, it mus
241a0 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69  t first be compi
241b0 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d  led into a byte-
241c0 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20  code.** program 
241d0 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65  using one of the
241e0 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
241f0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
24200 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20  ument, "db", is 
24210 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
24220 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64  ection] obtained
24230 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72   from a.** prior
24240 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
24250 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
24260 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
24270 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  pen_v2()] or.** 
24280 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
24290 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73  )].  The databas
242a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
242b0 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20  t not have been 
242c0 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  closed..**.** Th
242d0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
242e0 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68  t, "zSql", is th
242f0 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  e statement to b
24300 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f  e compiled, enco
24310 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72  ded.** as either
24320 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
24330 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  .  The sqlite3_p
24340 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c  repare() and sql
24350 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
24360 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
24370 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73  use UTF-8, and s
24380 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
24390 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
243a0 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a  repare16_v2().**
243b0 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a   use UTF-16..**.
243c0 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65  ** ^If the nByte
243d0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73   argument is les
243e0 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65  s than zero, the
243f0 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
24400 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73  p to the.** firs
24410 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
24420 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  r. ^If nByte is 
24430 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
24440 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78  en it is the max
24450 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f  imum.** number o
24460 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72  f  bytes read fr
24470 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20  om zSql.  ^When 
24480 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
24490 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53  ative, the.** zS
244a0 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61  ql string ends a
244b0 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72  t either the fir
244c0 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75  st '\000' or '\u
244d0 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20  0000' character 
244e0 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d  or.** the nByte-
244f0 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76  th byte, whichev
24500 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20  er comes first. 
24510 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e  If the caller kn
24520 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ows.** that the 
24530 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20  supplied string 
24540 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65  is nul-terminate
24550 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  d, then there is
24560 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66   a small.** perf
24570 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67  ormance advantag
24580 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62  e to be gained b
24590 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  y passing an nBy
245a0 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
245b0 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f  t.** is equal to
245c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
245d0 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75  ytes in the inpu
245e0 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c  t string <i>incl
245f0 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65  uding</i>.** the
24600 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20   nul-terminator 
24610 62 79 74 65 73 20 61 73 20 74 68 69 73 20 73 61  bytes as this sa
24620 76 65 73 20 53 51 4c 69 74 65 20 66 72 6f 6d 20  ves SQLite from 
24630 68 61 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b  having to.** mak
24640 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  e a copy of the 
24650 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a  input string..**
24660 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69  .** ^If pzTail i
24670 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
24680 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
24690 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
246a0 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61  first byte.** pa
246b0 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
246c0 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
246d0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
246e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
246f0 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  nly.** compile t
24700 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65  he first stateme
24710 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
24720 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
24730 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68  ointing to.** wh
24740 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d  at remains uncom
24750 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70  piled..**.** ^*p
24760 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
24770 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
24780 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
24790 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
247a0 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
247b0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
247c0 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74  _step()].  ^If t
247d0 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
247e0 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
247f0 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49  .** to NULL.  ^I
24800 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
24810 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
24820 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
24830 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
24840 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
24850 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
24860 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
24870 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  ** The calling p
24880 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
24890 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
248a0 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
248b0 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
248c0 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
248d0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
248e0 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
248f0 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20  hed with it..** 
24900 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62  ppStmt may not b
24910 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  e NULL..**.** ^O
24920 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73  n success, the s
24930 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
24940 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69   family of routi
24950 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
24960 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72  TE_OK];.** other
24970 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
24980 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
24990 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
249a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
249b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
249c0 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
249d0 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
249e0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
249f0 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
24a00 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
24a10 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
24a20 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
24a30 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
24a40 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
24a50 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
24a60 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22  ed..** ^In the "
24a70 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
24a80 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
24a90 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
24aa0 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
24ab0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
24ac0 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
24ad0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
24ae0 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
24af0 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
24b00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
24b10 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
24b20 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66  o.** behave diff
24b30 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65  erently in three
24b40 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
24b50 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  >.** <li>.** ^If
24b60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
24b70 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
24b80 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
24b90 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
24ba0 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
24bb0 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
24bc0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
24bd0 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
24be0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
24bf0 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
24c00 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
24c10 20 69 74 20 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f   it again..** </
24c20 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
24c30 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  * ^When an error
24c40 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65   occurs, [sqlite
24c50 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72  3_step()] will r
24c60 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65  eturn one of the
24c70 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72   detailed.** [er
24c80 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65  ror codes] or [e
24c90 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
24ca0 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61  des].  ^The lega
24cb0 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20  cy behavior was 
24cc0 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  that.** [sqlite3
24cd0 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f  _step()] would o
24ce0 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e  nly return a gen
24cf0 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52  eric [SQLITE_ERR
24d00 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a  OR] result code.
24d10 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ** and the appli
24d20 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76  cation would hav
24d30 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
24d40 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nd call to [sqli
24d50 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20  te3_reset()].** 
24d60 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
24d70 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
24d80 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
24d90 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22  blem. With the "
24da0 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69  v2" prepare.** i
24db0 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
24dc0 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
24dd0 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
24de0 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
24df0 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e  iately..** </li>
24e00 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
24e10 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20  If the specific 
24e20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b  value bound to [
24e30 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74  parameter | host
24e40 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
24e50 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61  he .** WHERE cla
24e60 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  use might influe
24e70 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f  nce the choice o
24e80 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72  f query plan for
24e90 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a   a statement,.**
24ea0 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d   then the statem
24eb0 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ent will be auto
24ec0 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
24ed0 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72  iled, as if ther
24ee0 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61  e had been .** a
24ef0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20   schema change, 
24f00 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73  on the first  [s
24f10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
24f20 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  all following an
24f30 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74  y change.** to t
24f40 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
24f50 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73  _text | bindings
24f60 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d  ] of that [param
24f70 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20  eter]. .** ^The 
24f80 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f  specific value o
24f90 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b  f WHERE-clause [
24fa0 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74  parameter] might
24fb0 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a   influence the .
24fc0 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  ** choice of que
24fd0 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70  ry plan if the p
24fe0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
24ff0 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  left-hand side o
25000 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72  f a [LIKE].** or
25010 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
25020 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d   or if the param
25030 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64  eter is compared
25040 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63   to an indexed c
25050 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65  olumn.** and the
25060 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
25070 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74  STAT3] compile-t
25080 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e  ime option is en
25090 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a  abled..** the .*
250a0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e  * </li>.** </ol>
250b0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
250c0 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
250d0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
250e0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
250f0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
25100 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
25110 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
25120 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
25130 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
25140 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
25150 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
25160 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
25170 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
25180 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
25190 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
251a0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
251b0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
251c0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
251d0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
251e0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
251f0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
25200 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20  e3_prepare_v2(. 
25210 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
25220 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
25230 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
25240 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
25250 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
25260 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
25270 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
25280 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
25290 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
252a0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
252b0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
252c0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
252d0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
252e0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
252f0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
25300 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
25310 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
25320 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
25330 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
25340 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
25350 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
25360 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
25370 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
25380 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
25390 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
253a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
253b0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
253c0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
253d0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
253e0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
253f0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
25400 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
25410 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
25420 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
25430 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
25440 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
25450 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
25460 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
25470 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
25480 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
25490 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73  repare16_v2(.  s
254a0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
254b0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
254c0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
254d0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
254e0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
254f0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
25500 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
25510 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
25520 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
25530 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
25540 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
25550 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
25560 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
25570 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
25580 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
25590 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
255a0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
255b0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
255c0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   zSql */.);../*.
255d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74  ** CAPI3REF: Ret
255e0 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e  rieving Statemen
255f0 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  t SQL.**.** ^Thi
25600 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
25610 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  be used to retri
25620 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79  eve a saved copy
25630 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
25640 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
25650 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70  d to create a [p
25660 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25670 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65  t] if that state
25680 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70  ment was.** comp
25690 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
256a0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
256b0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
256c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
256d0 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  2()]..*/.const c
256e0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c  har *sqlite3_sql
256f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
25700 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
25710 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
25720 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
25730 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65  ement Writes The
25740 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20   Database.**.** 
25750 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
25760 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e  t_readonly(X) in
25770 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
25780 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
25790 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69  if.** and only i
257a0 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
257b0 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b  statement] X mak
257c0 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61  es no direct cha
257d0 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63  nges to.** the c
257e0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
257f0 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a  tabase file..**.
25800 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70  ** Note that [ap
25810 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
25820 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
25830 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20   or.** [virtual 
25840 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68  tables] might ch
25850 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
25860 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20  e indirectly as 
25870 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20  a side effect.  
25880 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
25890 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  e, if an applica
258a0 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66  tion defines a f
258b0 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22  unction "eval()"
258c0 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20   that .** calls 
258d0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
258e0 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f  , then the follo
258f0 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  wing SQL stateme
25900 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e  nt would.** chan
25910 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
25920 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64  file through sid
25930 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a  e-effects:.**.**
25940 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
25950 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20  e>.**    SELECT 
25960 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f  eval('DELETE FRO
25970 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a  M t1') FROM t2;.
25980 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
25990 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74  quote>.**.** But
259a0 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45   because the [SE
259b0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
259c0 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
259d0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
259e0 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73  e.** directly, s
259f0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
25a00 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69  only() would sti
25a10 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29  ll return true.)
25a20 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63  ^.**.** ^Transac
25a30 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61  tion control sta
25a40 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20  tements such as 
25a50 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54  [BEGIN], [COMMIT
25a60 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a  ], [ROLLBACK],.*
25a70 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61  * [SAVEPOINT], a
25a80 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75  nd [RELEASE] cau
25a90 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  se sqlite3_stmt_
25aa0 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
25ab0 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69  turn true,.** si
25ac0 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  nce the statemen
25ad0 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f  ts themselves do
25ae0 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f   not actually mo
25af0 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
25b00 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20  e but.** rather 
25b10 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65  they control the
25b20 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20   timing of when 
25b30 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73  other statements
25b40 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20   modify the .** 
25b50 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20  database.  ^The 
25b60 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45  [ATTACH] and [DE
25b70 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73  TACH] statements
25b80 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73   also cause.** s
25b90 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
25ba0 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
25bb0 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69   true since, whi
25bc0 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65  le those stateme
25bd0 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  nts.** change th
25be0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
25bf0 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  of a database co
25c00 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64  nnection, they d
25c10 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63  o not make .** c
25c20 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f  hanges to the co
25c30 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
25c40 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64  abase files on d
25c50 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  isk..*/.int sqli
25c60 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
25c70 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  y(sqlite3_stmt *
25c80 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
25c90 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
25ca0 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64  ne If A Prepared
25cb0 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42   Statement Has B
25cc0 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20  een Reset.**.** 
25cd0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
25ce0 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66  t_busy(S) interf
25cf0 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
25d00 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74   (non-zero) if t
25d10 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
25d20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73  statement] S has
25d30 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74   been stepped at
25d40 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e   least once usin
25d50 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  g .** [sqlite3_s
25d60 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20  tep(S)] but has 
25d70 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c  not run to compl
25d80 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73  etion and/or has
25d90 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65   not .** been re
25da0 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  set using [sqlit
25db0 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e  e3_reset(S)].  ^
25dc0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
25dd0 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65  _busy(S).** inte
25de0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61  rface returns fa
25df0 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55  lse if S is a NU
25e00 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20  LL pointer.  If 
25e10 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e  S is not a .** N
25e20 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  ULL pointer and 
25e30 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72  is not a pointer
25e40 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65   to a valid [pre
25e50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25e60 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e  .** object, then
25e70 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
25e80 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
25e90 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
25ea0 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ble..**.** This 
25eb0 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
25ec0 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61   used in combina
25ed0 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65  tion [sqlite3_ne
25ee0 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f  xt_stmt()].** to
25ef0 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70   locate all prep
25f00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20  ared statements 
25f10 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
25f20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63  a database .** c
25f30 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61  onnection that a
25f40 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65  re in need of be
25f50 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73  ing reset.  This
25f60 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a   can be used,.**
25f70 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e   for example, in
25f80 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74   diagnostic rout
25f90 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66  ines to search f
25fa0 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20  or prepared .** 
25fb0 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
25fc0 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72  are holding a tr
25fd0 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a  ansaction open..
25fe0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
25ff0 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33  tmt_busy(sqlite3
26000 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
26010 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69  CAPI3REF: Dynami
26020 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
26030 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  e Object.** KEYW
26040 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
26050 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
26060 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
26070 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
26080 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
26090 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
260a0 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
260b0 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
260c0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
260d0 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
260e0 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65  se table. SQLite
260f0 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79   uses dynamic ty
26100 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ping.** for the 
26110 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
26120 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65  .  ^Values store
26130 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
26140 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
26150 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
26160 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
26170 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
26180 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
26190 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
261a0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
261b0 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
261c0 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
261d0 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
261e0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
261f0 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
26200 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
26210 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
26220 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
26230 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
26240 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
26250 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
26260 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
26270 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
26280 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
26290 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
262a0 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
262b0 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
262c0 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
262d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
262e0 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
262f0 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
26300 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
26310 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
26320 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
26330 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74  is held.  An int
26340 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
26350 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
26360 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
26370 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
26380 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
26390 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
263a0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
263b0 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
263c0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
263d0 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
263e0 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
263f0 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  th [SQLITE_THREA
26400 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74  DSAFE=0] and wit
26410 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
26420 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
26430 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53  ng 0).** or if S
26440 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20  QLite is run in 
26450 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d  one of reduced m
26460 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b  utex modes .** [
26470 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
26480 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b  NGLETHREAD] or [
26490 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
264a0 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68  LTITHREAD].** th
264b0 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64  en there is no d
264c0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
264d0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
264e0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
264f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
26500 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63  jects and they c
26510 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72  an be used inter
26520 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77  changeably.  How
26530 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78  ever,.** for max
26540 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62  imum code portab
26550 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f  ility it is reco
26560 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
26570 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69  lications.** sti
26580 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ll make the dist
26590 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
265a0 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
265b0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
265c0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
265d0 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
265e0 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
265f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
26600 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
26610 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
26620 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
26630 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
26640 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
26650 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
26660 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
26670 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
26680 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
26690 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
266a0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
266b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
266c0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
266d0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
266e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
266f0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
26700 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
26710 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
26720 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
26730 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
26740 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
26750 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
26760 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
26770 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
26780 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
26790 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
267a0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
267b0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
267c0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
267d0 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
267e0 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
267f0 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69  3REF: SQL Functi
26800 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
26810 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  t.**.** The cont
26820 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
26830 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
26840 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
26850 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
26860 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
26870 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20    ^A pointer to 
26880 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  an sqlite3_conte
26890 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20  xt object.** is 
268a0 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72  always first par
268b0 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69  ameter to [appli
268c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
268d0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  QL functions]..*
268e0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
268f0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
26900 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
26910 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20  ation will pass 
26920 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  this.** pointer 
26930 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c  through into cal
26940 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
26950 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69  esult_int | sqli
26960 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a  te3_result()],.*
26970 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  * [sqlite3_aggre
26980 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c  gate_context()],
26990 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
269a0 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ata()],.** [sqli
269b0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
269c0 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74  andle()], [sqlit
269d0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
269e0 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71  ],.** and/or [sq
269f0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
26a00 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  a()]..*/.typedef
26a10 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
26a20 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
26a30 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
26a40 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e  CAPI3REF: Bindin
26a50 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
26a60 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a  ared Statements.
26a70 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f  ** KEYWORDS: {ho
26a80 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68  st parameter} {h
26a90 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20  ost parameters} 
26aa0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  {host parameter 
26ab0 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  name}.** KEYWORD
26ac0 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  S: {SQL paramete
26ad0 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  r} {SQL paramete
26ae0 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62  rs} {parameter b
26af0 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28  inding}.**.** ^(
26b00 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  In the SQL state
26b10 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20  ment text input 
26b20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
26b30 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74  are_v2()] and it
26b40 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c  s variants,.** l
26b50 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72  iterals may be r
26b60 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61  eplaced by a [pa
26b70 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61  rameter] that ma
26b80 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c  tches one of fol
26b90 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61  lowing.** templa
26ba0 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  tes:.**.** <ul>.
26bb0 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c  ** <li>  ?.** <l
26bc0 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e  i>  ?NNN.** <li>
26bd0 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    :VVV.** <li>  
26be0 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56  @VVV.** <li>  $V
26bf0 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VV.** </ul>.**.*
26c00 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74  * In the templat
26c10 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65  es above, NNN re
26c20 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65  presents an inte
26c30 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
26c40 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e  and VVV represen
26c50 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72  ts an alphanumer
26c60 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e  ic identifier.)^
26c70 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66    ^The values of
26c80 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65   these.** parame
26c90 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
26ca0 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
26cb0 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c  r names" or "SQL
26cc0 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a   parameters").**
26cd0 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e   can be set usin
26ce0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
26cf0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
26d00 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a  defined here..**
26d10 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
26d20 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
26d30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
26d40 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61  routines is alwa
26d50 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ys.** a pointer 
26d60 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
26d70 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74  stmt] object ret
26d80 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73  urned from.** [s
26d90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
26da0 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  2()] or its vari
26db0 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ants..**.** ^The
26dc0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
26dd0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
26de0 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
26df0 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a  er to be set..**
26e00 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53   ^The leftmost S
26e10 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  QL parameter has
26e20 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20   an index of 1. 
26e30 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20   ^When the same 
26e40 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72  named.** SQL par
26e50 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d  ameter is used m
26e60 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73  ore than once, s
26e70 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
26e80 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e  uent.** occurren
26e90 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d  ces have the sam
26ea0 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66  e index as the f
26eb0 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e  irst occurrence.
26ec0 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66  .** ^The index f
26ed0 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  or named paramet
26ee0 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65  ers can be looke
26ef0 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a  d up using the.*
26f00 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
26f10 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
26f20 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
26f30 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a  d.  ^The index.*
26f40 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72  * for "?NNN" par
26f50 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76  ameters is the v
26f60 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
26f70 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d  ^The NNN value m
26f80 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
26f90 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65   and the [sqlite
26fa0 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61  3_limit()].** pa
26fb0 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f  rameter [SQLITE_
26fc0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
26fd0 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20  UMBER] (default 
26fe0 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a  value: 999)..**.
26ff0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  ** ^The third ar
27000 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61  gument is the va
27010 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74  lue to bind to t
27020 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
27030 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72  .** ^(In those r
27040 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
27050 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
27060 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
27070 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
27080 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
27090 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
270a0 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
270b0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
270c0 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
270d0 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
270e0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
270f0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29   of characters.)
27100 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75  ^.** ^If the fou
27110 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
27120 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
27130 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
27140 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
27150 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
27160 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  en the length of
27170 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
27180 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
27190 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
271a0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
271b0 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65  nator..** If the
271c0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
271d0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
271e0 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61  d_blob() is nega
271f0 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  tive, then.** th
27200 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
27210 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61  defined..** If a
27220 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f   non-negative fo
27230 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
27240 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71  s provided to sq
27250 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
27260 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
27270 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68  bind_text16() th
27280 65 6e 20 74 68 61 74 20 70 61 72 61 6d 65 74 65  en that paramete
27290 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  r must be the by
272a0 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65  te offset.** whe
272b0 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
272c0 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75  nator would occu
272d0 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73  r assuming the s
272e0 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a  tring were NUL.*
272f0 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  * terminated.  I
27300 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
27310 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79  ters occur at by
27320 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20  te offsets less 
27330 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c  than .** the val
27340 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  ue of the fourth
27350 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20   parameter then 
27360 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
27370 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a  ring value will.
27380 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ** contain embed
27390 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72  ded NULs.  The r
273a0 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73  esult of express
273b0 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73  ions involving s
273c0 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65  trings.** with e
273d0 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20  mbedded NULs is 
273e0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
273f0 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
27400 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
27410 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  bind_blob(), sql
27420 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
27430 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  , and.** sqlite3
27440 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69  _bind_text16() i
27450 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
27460 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
27470 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
27480 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51   string after SQ
27490 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
274a0 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65  d with it.  ^The
274b0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
274c0 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70  alled.** to disp
274d0 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
274e0 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69  or string even i
274f0 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71  f the call to sq
27500 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
27510 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69  ),.** sqlite3_bi
27520 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71  nd_text(), or sq
27530 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
27540 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20  6() fails.  .** 
27550 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
27560 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
27570 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
27580 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
27590 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
275a0 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
275b0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
275c0 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
275d0 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
275e0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
275f0 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  e freed..** ^If 
27600 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
27610 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
27620 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
27630 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
27640 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
27650 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
27660 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
27670 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
27680 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
27690 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
276a0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
276b0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
276c0 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
276d0 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
276e0 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
276f0 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
27700 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a  th zeroes.  ^A z
27710 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
27720 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
27730 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
27740 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
27750 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c  d its size) whil
27760 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
27770 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
27780 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
27790 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
277a0 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
277b0 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63  BLOBs whose.** c
277c0 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20  ontent is later 
277d0 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a  written using.**
277e0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
277f0 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
27800 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  l BLOB I/O] rout
27810 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61  ines..** ^A nega
27820 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
27830 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
27840 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
27850 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
27860 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20   ^If any of the 
27870 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
27880 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
27890 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
278a0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20   pointer.** for 
278b0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
278c0 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68  atement] or with
278d0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
278e0 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a  ement for which.
278f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
27900 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  ()] has been cal
27910 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c  led more recentl
27920 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f  y than [sqlite3_
27930 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65  reset()],.** the
27940 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20  n the call will 
27950 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d  return [SQLITE_M
27960 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20  ISUSE].  If any 
27970 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a  sqlite3_bind_().
27980 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  ** routine is pa
27990 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64  ssed a [prepared
279a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
279b0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
279c0 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75  zed, the.** resu
279d0 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  lt is undefined 
279e0 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72  and probably har
279f0 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e  mful..**.** ^Bin
27a00 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
27a10 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
27a20 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
27a30 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f  outine..** ^Unbo
27a40 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
27a50 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
27a60 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
27a70 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
27a80 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  * routines retur
27a90 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
27aa0 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a   success or an.*
27ab0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  * [error code] i
27ac0 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  f anything goes 
27ad0 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  wrong..** ^[SQLI
27ae0 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
27af0 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
27b00 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
27b10 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
27b20 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d    ^[SQLITE_NOMEM
27b30 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
27b40 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
27b50 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
27b60 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
27b70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
27b80 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
27b90 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
27ba0 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  me()], and [sqli
27bb0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
27bc0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
27bd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
27be0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
27bf0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
27c00 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
27c10 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
27c20 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
27c30 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
27c40 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
27c50 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
27c60 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33  bind_int(sqlite3
27c70 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
27c80 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
27c90 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ind_int64(sqlite
27ca0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
27cb0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e  lite3_int64);.in
27cc0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  t sqlite3_bind_n
27cd0 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ull(sqlite3_stmt
27ce0 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  *, int);.int sql
27cf0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73  ite3_bind_text(s
27d00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
27d10 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  t, const char*, 
27d20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
27d30 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
27d40 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
27d50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
27d60 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
27d70 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
27d80 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
27d90 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
27da0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
27db0 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
27dc0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
27dd0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
27de0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
27df0 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a  , int, int n);..
27e00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27e10 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61  Number Of SQL Pa
27e20 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e  rameters.**.** ^
27e30 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
27e40 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
27e50 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
27e60 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
27e70 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
27e80 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
27e90 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
27ea0 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
27eb0 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
27ec0 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
27ed0 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
27ee0 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
27ef0 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
27f00 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
27f10 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
27f20 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
27f30 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
27f40 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
27f50 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e..**.** ^(This 
27f60 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
27f70 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
27f80 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
27f90 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
27fa0 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
27fb0 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
27fc0 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
27fd0 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
27fe0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
27ff0 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
28000 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
28010 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f  s of the ?NNN fo
28020 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20  rm are used,.** 
28030 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70  there may be gap
28040 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e  s in the list.)^
28050 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
28060 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
28070 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
28080 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
28090 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
280a0 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  name()], and.** 
280b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
280c0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
280d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
280e0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
280f0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
28100 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
28110 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
28120 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
28130 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
28140 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
28150 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65  r_name(P,N) inte
28160 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
28170 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
28180 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d   N-th [SQL param
28190 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72  eter] in the [pr
281a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
281b0 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61  ] P..** ^(SQL pa
281c0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
281d0 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  form "?NNN" or "
281e0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
281f0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76  or "$AAA".** hav
28200 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69  e a name which i
28210 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e  s the string "?N
28220 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
28230 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
28240 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ".** respectivel
28250 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  y..** In other w
28260 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61  ords, the initia
28270 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20  l ":" or "$" or 
28280 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73  "@" or "?".** is
28290 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72   included as par
282a0 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e  t of the name.)^
282b0 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20  .** ^Parameters 
282c0 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20  of the form "?" 
282d0 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77  without a follow
282e0 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65  ing integer have
282f0 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20   no name.** and 
28300 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20  are referred to 
28310 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72  as "nameless" or
28320 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61   "anonymous para
28330 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e  meters"..**.** ^
28340 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70  The first host p
28350 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
28360 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
28370 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  0..**.** ^If the
28380 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20   value N is out 
28390 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74  of range or if t
283a0 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65  he N-th paramete
283b0 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73  r is.** nameless
283c0 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72  , then NULL is r
283d0 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72  eturned.  ^The r
283e0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
283f0 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55  s.** always in U
28400 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
28410 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
28420 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
28430 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
28440 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
28450 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
28460 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b  are16()] or.** [
28470 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
28480 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
28490 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
284a0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
284b0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
284c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
284d0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
284e0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
284f0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
28500 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f  _index()]..*/.co
28510 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
28520 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
28530 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
28540 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
28550 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
28560 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
28570 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
28580 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  me.**.** ^Return
28590 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
285a0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67   SQL parameter g
285b0 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20  iven its name.  
285c0 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61  ^The.** index va
285d0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
285e0 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65  suitable for use
285f0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
28600 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  * parameter to [
28610 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
28620 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
28630 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69  ].  ^A zero.** i
28640 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f  s returned if no
28650 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65   matching parame
28660 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e  ter is found.  ^
28670 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
28680 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
28690 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
286a0 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
286b0 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
286c0 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
286d0 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
286e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
286f0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
28700 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
28710 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
28720 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
28730 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
28740 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
28750 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
28760 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
28770 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
28780 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
28790 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
287a0 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
287b0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
287c0 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
287d0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
287e0 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
287f0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
28800 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72  t.**.** ^Contrar
28810 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69  y to the intuiti
28820 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c  on of many, [sql
28830 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f  ite3_reset()] do
28840 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20  es not reset.** 
28850 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
28860 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67  d_blob | binding
28870 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  s] on a [prepare
28880 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
28890 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69   ^Use this routi
288a0 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
288b0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
288c0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20  to NULL..*/.int 
288d0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
288e0 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
288f0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
28900 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
28910 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52  f Columns In A R
28920 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20  esult Set.**.** 
28930 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62  ^Return the numb
28940 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
28950 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
28960 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
28970 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
28980 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72  tement]. ^This r
28990 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
289a0 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20   if pStmt is an 
289b0 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
289c0 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72   that does not r
289d0 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20  eturn data (for 
289e0 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41  example an [UPDA
289f0 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  TE])..**.** See 
28a00 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64  also: [sqlite3_d
28a10 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  ata_count()].*/.
28a20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
28a30 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  mn_count(sqlite3
28a40 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
28a50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28a60 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20  Column Names In 
28a70 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a  A Result Set.**.
28a80 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
28a90 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
28aa0 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
28ab0 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
28ac0 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
28ad0 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
28ae0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
28af0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63    ^The sqlite3_c
28b00 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
28b10 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
28b20 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
28b30 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
28b40 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
28b50 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
28b60 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74  umn_name16() ret
28b70 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
28b80 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
28b90 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
28ba0 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73  ring.  ^The firs
28bb0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
28bc0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
28bd0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20  tement].** that 
28be0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b  implements the [
28bf0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
28c00 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  t. ^The second p
28c10 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
28c20 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  ** column number
28c30 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  .  ^The leftmost
28c40 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
28c50 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r 0..**.** ^The 
28c60 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
28c70 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
28c80 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
28c90 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
28ca0 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73  ement].** is des
28cb0 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
28cc0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
28cd0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
28ce0 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
28cf0 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
28d00 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
28d10 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
28d20 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
28d30 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
28d40 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
28d50 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  next call to.** 
28d60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
28d70 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
28d80 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
28d90 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
28da0 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73  umn..**.** ^If s
28db0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
28dc0 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
28dd0 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
28de0 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
28df0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
28e00 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
28e10 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
28e20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
28e30 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
28e40 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
28e50 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  * ^The name of a
28e60 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
28e70 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
28e80 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
28e90 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
28ea0 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
28eb0 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
28ec0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
28ed0 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
28ee0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
28ef0 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
28f00 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
28f10 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
28f20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
28f30 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
28f40 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
28f50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
28f60 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
28f70 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76   int N);.const v
28f80 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
28f90 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  umn_name16(sqlit
28fa0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
28fb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28fc0 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74  F: Source Of Dat
28fd0 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73  a In A Query Res
28fe0 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ult.**.** ^These
28ff0 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64   routines provid
29000 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74  e a means to det
29010 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62  ermine the datab
29020 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a  ase, table, and.
29030 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  ** table column 
29040 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67  that is the orig
29050 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c  in of a particul
29060 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ar result column
29070 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20   in.** [SELECT] 
29080 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54  statement..** ^T
29090 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
290a0 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65  atabase or table
290b0 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62   or column can b
290c0 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
290d0 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20   either a UTF-8 
290e0 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
290f0 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73  .  ^The _databas
29100 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
29110 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  rn.** the databa
29120 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61  se name, the _ta
29130 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ble_ routines re
29140 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e  turn the table n
29150 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20  ame, and.** the 
29160 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73  origin_ routines
29170 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75   return the colu
29180 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65  mn name..** ^The
29190 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
291a0 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
291b0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
291c0 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
291d0 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  royed.** using [
291e0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
291f0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
29200 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
29210 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
29220 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
29230 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
29240 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
29250 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
29260 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
29270 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
29280 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
29290 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61  ed.** again in a
292a0 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64   different encod
292b0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ing..**.** ^The 
292c0 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61  names returned a
292d0 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  re the original 
292e0 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73  un-aliased names
292f0 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   of the.** datab
29300 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20  ase, table, and 
29310 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  column..**.** ^T
29320 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
29330 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  t to these inter
29340 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70  faces is a [prep
29350 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
29360 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
29370 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ions return info
29380 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
29390 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c  e Nth result col
293a0 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a  umn returned by.
293b0 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
293c0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
293d0 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
293e0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
293f0 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
29400 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20  umn is column 0 
29410 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
29420 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  es..**.** ^If th
29430 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
29440 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61  urned by the sta
29450 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70  tement is an exp
29460 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75  ression or.** su
29470 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f  bquery and is no
29480 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  t a column value
29490 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68  , then all of th
294a0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
294b0 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e  turn.** NULL.  ^
294c0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69  These routine mi
294d0 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  ght also return 
294e0 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79  NULL if a memory
294f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
29500 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f  r.** occurs.  ^O
29510 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72  therwise, they r
29520 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f  eturn the name o
29530 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64  f the attached d
29540 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a  atabase, table,.
29550 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61  ** or column tha
29560 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63  t query result c
29570 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63  olumn was extrac
29580 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20  ted from..**.** 
29590 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68  ^As with all oth
295a0 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20  er SQLite APIs, 
295b0 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65  those whose name
295c0 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20  s end with "16" 
295d0 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36  return.** UTF-16
295e0 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73   encoded strings
295f0 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66   and the other f
29600 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
29610 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  UTF-8..**.** ^Th
29620 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c  ese APIs are onl
29630 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
29640 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
29650 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
29660 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
29670 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
29680 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73  TA] C-preprocess
29690 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a  or symbol..**.**
296a0 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
296b0 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
296c0 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73   or more of thes
296d0 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e  e routines again
296e0 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70  st the same.** p
296f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29700 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20  t and column at 
29710 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
29720 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
29730 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  re.** undefined.
29740 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
29750 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
29760 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  ll one or more.*
29770 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
29780 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
29790 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
297a0 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
297b0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70   for the same [p
297c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
297d0 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f  t] and result co
297e0 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73  lumn.** at the s
297f0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
29800 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
29810 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73  defined..*/.cons
29820 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
29830 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
29840 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
29850 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
29860 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
29870 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
29880 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
29890 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
298a0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
298b0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
298c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
298d0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
298e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
298f0 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
29900 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
29910 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
29920 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
29930 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
29940 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
29950 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
29960 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
29970 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
29980 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
29990 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
299a0 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
299b0 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a  ery Result.**.**
299c0 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72   ^(The first par
299d0 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65  ameter is a [pre
299e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
299f0 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61  ..** If this sta
29a00 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c  tement is a [SEL
29a10 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ECT] statement a
29a20 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  nd the Nth colum
29a30 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75  n of the.** retu
29a40 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20  rned result set 
29a50 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d  of that [SELECT]
29a60 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
29a70 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
29a80 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
29a90 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
29aa0 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
29ab0 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
29ac0 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
29ad0 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20  )^  ^If the Nth 
29ae0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
29af0 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a  sult set is an.*
29b00 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
29b10 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61  subquery, then a
29b20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
29b30 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54   returned..** ^T
29b40 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
29b50 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46  ng is always UTF
29b60 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a  -8 encoded..**.*
29b70 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
29b80 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62   given the datab
29b90 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a  ase schema:.**.*
29ba0 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  * CREATE TABLE t
29bb0 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a  1(c1 VARIANT);.*
29bc0 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c  *.** and the fol
29bd0 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
29be0 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a   to be compiled:
29bf0 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31  .**.** SELECT c1
29c00 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31   + 1, c1 FROM t1
29c10 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ;.**.** this rou
29c20 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72  tine would retur
29c30 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41  n the string "VA
29c40 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73  RIANT" for the s
29c50 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20  econd result.** 
29c60 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61  column (i==1), a
29c70 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nd a NULL pointe
29c80 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  r for the first 
29c90 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69  result column (i
29ca0 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  ==0).)^.**.** ^S
29cb0 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
29cc0 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69  ic run-time typi
29cd0 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65  ng.  ^So just be
29ce0 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a  cause a column.*
29cf0 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f  * is declared to
29d00 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69   contain a parti
29d10 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20  cular type does 
29d20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68  not mean that th
29d30 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64  e.** data stored
29d40 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20   in that column 
29d50 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72  is of the declar
29d60 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65  ed type.  SQLite
29d70 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20   is.** strongly 
29d80 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74  typed, but the t
29d90 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63  yping is dynamic
29da0 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54   not static.  ^T
29db0 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69  ype.** is associ
29dc0 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69  ated with indivi
29dd0 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74  dual values, not
29de0 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69   with the contai
29df0 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20  ners.** used to 
29e00 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65  hold those value
29e10 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  s..*/.const char
29e20 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
29e30 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65  _decltype(sqlite
29e40 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
29e50 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
29e60 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
29e70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
29e80 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
29e90 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74  API3REF: Evaluat
29ea0 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  e An SQL Stateme
29eb0 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61  nt.**.** After a
29ec0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29ed0 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
29ee0 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69  repared using ei
29ef0 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
29f00 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
29f10 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
29f20 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  re16_v2()] or on
29f30 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a  e of the legacy.
29f40 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
29f50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
29f60 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
29f70 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73  epare16()], this
29f80 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73   function.** mus
29f90 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20  t be called one 
29fa0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
29fb0 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74   evaluate the st
29fc0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  atement..**.** T
29fd0 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68  he details of th
29fe0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
29ff0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
2a000 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e   interface depen
2a010 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  d.** on whether 
2a020 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
2a030 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  s prepared using
2a040 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20   the newer "v2" 
2a050 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71  interface.** [sq
2a060 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2a070 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2a080 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2a090 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
2a0a0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2a0b0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
2a0c0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
2a0d0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
2a0e0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
2a0f0 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74  .** new "v2" int
2a100 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
2a110 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
2a120 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
2a130 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
2a140 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
2a150 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
2a160 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20  rted..**.** ^In 
2a170 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2a180 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
2a190 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
2a1a0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
2a1b0 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
2a1c0 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
2a1d0 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
2a1e0 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
2a1f0 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74  MISUSE]..** ^Wit
2a200 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
2a210 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
2a220 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
2a230 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
2a240 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
2a250 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
2a260 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
2a270 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55  *.** ^[SQLITE_BU
2a280 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SY] means that t
2a290 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
2a2a0 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f  ne was unable to
2a2b0 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20   acquire the.** 
2a2c0 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69  database locks i
2a2d0 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74  t needs to do it
2a2e0 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20  s job.  ^If the 
2a2f0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
2a300 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
2a310 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
2a320 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
2a330 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
2a340 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
2a350 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
2a360 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
2a370 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
2a380 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
2a390 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63  hin an.** explic
2a3a0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
2a3b0 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
2a3c0 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
2a3d0 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
2a3e0 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
2a3f0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e  .** ^[SQLITE_DON
2a400 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
2a410 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
2a420 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
2a430 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
2a440 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
2a450 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
2a460 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
2a470 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
2a480 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
2a490 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
2a4a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2a4b0 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
2a4c0 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
2a4d0 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
2a4e0 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
2a4f0 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73  ** ^If the SQL s
2a500 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
2a510 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
2a520 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b  any data, then [
2a530 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69  SQLITE_ROW].** i
2a540 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
2a550 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
2a560 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20  f data is ready 
2a570 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
2a580 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e  y the.** caller.
2a590 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
2a5a0 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
2a5b0 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63  g the [column ac
2a5c0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
2a5d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
2a5e0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
2a5f0 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
2a600 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
2a610 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ata..**.** ^[SQL
2a620 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
2a630 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
2a640 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
2a650 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
2a660 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
2a670 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
2a680 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
2a690 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
2a6a0 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
2a6b0 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
2a6c0 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
2a6d0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
2a6e0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
2a6f0 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61  * ^With the lega
2a700 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
2a710 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
2a720 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78  ror code (for ex
2a730 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ample,.** [SQLIT
2a740 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
2a750 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
2a760 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
2a770 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
2a780 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
2a790 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
2a7a0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2a7b0 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
2a7c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
2a7d0 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
2a7e0 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
2a7f0 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
2a800 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
2a810 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
2a820 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
2a830 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
2a840 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
2a850 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
2a860 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
2a870 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
2a880 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
2a890 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
2a8a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a8b0 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
2a8c0 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
2a8d0 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
2a8e0 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
2a8f0 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
2a900 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
2a910 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
2a920 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
2a930 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
2a940 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
2a950 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
2a960 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2a970 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
2a980 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
2a990 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
2a9a0 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
2a9b0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  time..**.** For 
2a9c0 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  all versions of 
2a9d0 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64  SQLite up to and
2a9e0 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32   including 3.6.2
2a9f0 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  3.1, a call to.*
2aa00 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2aa10 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64  ()] was required
2aa20 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73   after sqlite3_s
2aa30 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61  tep() returned a
2aa40 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  nything.** other
2aa50 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
2aa60 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75  W] before any su
2aa70 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
2aa80 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65  ion of.** sqlite
2aa90 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75  3_step().  Failu
2aaa0 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  re to reset the 
2aab0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2aac0 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  nt using .** [sq
2aad0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
2aae0 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
2aaf0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
2ab00 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a  ] return from.**
2ab10 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
2ab20 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73    But after vers
2ab30 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71  ion 3.6.23.1, sq
2ab40 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67  lite3_step() beg
2ab50 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73  an.** calling [s
2ab60 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2ab70 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
2ab80 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e   this circumstan
2ab90 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61  ce rather.** tha
2aba0 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  n returning [SQL
2abb0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68  ITE_MISUSE].  Th
2abc0 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64  is is not consid
2abd0 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69  ered a compatibi
2abe0 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65  lity.** break be
2abf0 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63  cause any applic
2ac00 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20  ation that ever 
2ac10 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49  receives an SQLI
2ac20 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a  TE_MISUSE error.
2ac30 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20  ** is broken by 
2ac40 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65  definition.  The
2ac50 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
2ac60 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65  TORESET] compile
2ac70 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  -time option.** 
2ac80 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
2ac90 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63  estore the legac
2aca0 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  y behavior..**.*
2acb0 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72  * <b>Goofy Inter
2acc0 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20  face Alert:</b> 
2acd0 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
2ace0 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c  terface, the sql
2acf0 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41  ite3_step().** A
2ad00 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  PI always return
2ad10 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f  s a generic erro
2ad20 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f  r code, [SQLITE_
2ad30 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e  ERROR], followin
2ad40 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f  g any.** error o
2ad50 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
2ad60 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c  E_BUSY] and [SQL
2ad70 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f  ITE_MISUSE].  Yo
2ad80 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b  u must call.** [
2ad90 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2ada0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
2adb0 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65  alize()] in orde
2adc0 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66  r to find one of
2add0 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
2ade0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74   [error codes] t
2adf0 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72  hat better descr
2ae00 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a  ibes the error..
2ae10 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ** We admit that
2ae20 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79   this is a goofy
2ae30 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72   design.  The pr
2ae40 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66  oblem has been f
2ae50 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ixed.** with the
2ae60 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e   "v2" interface.
2ae70 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65    If you prepare
2ae80 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c   all of your SQL
2ae90 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75   statements.** u
2aea0 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
2aeb0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2aec0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
2aed0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69  repare16_v2()] i
2aee0 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
2aef0 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
2af00 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
2af10 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2af20 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  16()] interfaces
2af30 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f  ,.** then the mo
2af40 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  re specific [err
2af50 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65  or codes] are re
2af60 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a  turned directly.
2af70 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ** by sqlite3_st
2af80 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f  ep().  The use o
2af90 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  f the "v2" inter
2afa0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
2afb0 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ded..*/.int sqli
2afc0 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33  te3_step(sqlite3
2afd0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2afe0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
2aff0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
2b000 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a   result set.**.*
2b010 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2b020 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74  ata_count(P) int
2b030 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2b040 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2b050 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63  umns in the.** c
2b060 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
2b070 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
2b080 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b090 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70  ent] P..** ^If p
2b0a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b0b0 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  t P does not hav
2b0c0 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20  e results ready 
2b0d0 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69  to return.** (vi
2b0e0 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b  a calls to the [
2b0f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2b100 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt | sqlite3_col
2b110 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69  umn_*()] of.** i
2b120 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20  nterfaces) then 
2b130 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2b140 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e  nt(P) returns 0.
2b150 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b160 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
2b170 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75  outine also retu
2b180 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20  rns 0 if P is a 
2b190 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2b1a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2b1b0 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
2b1c0 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
2b1d0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
2b1e0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2b1f0 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
2b200 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ned [SQLITE_DONE
2b210 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
2b220 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a  _data_count(P).*
2b230 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f  * will return no
2b240 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f  n-zero if previo
2b250 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  us call to [sqli
2b260 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
2b270 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  urned.** [SQLITE
2b280 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e  _ROW], except in
2b290 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65   the case of the
2b2a0 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65   [PRAGMA increme
2b2b0 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20  ntal_vacuum].** 
2b2c0 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20  where it always 
2b2d0 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e  returns zero sin
2b2e0 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20  ce each step of 
2b2f0 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a  that multi-step.
2b300 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e  ** pragma return
2b310 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64  s 0 columns of d
2b320 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ata..**.** See a
2b330 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  lso: [sqlite3_co
2b340 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  lumn_count()].*/
2b350 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74  .int sqlite3_dat
2b360 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  a_count(sqlite3_
2b370 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2b380 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
2b390 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74  undamental Datat
2b3a0 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
2b3b0 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a  : SQLITE_TEXT.**
2b3c0 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75  .** ^(Every valu
2b3d0 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
2b3e0 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
2b3f0 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
2b400 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2b410 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
2b420 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
2b430 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
2b440 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
2b450 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
2b460 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
2b470 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
2b480 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
2b490 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
2b4a0 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
2b4b0 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
2b4c0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
2b4d0 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
2b4e0 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
2b4f0 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
2b500 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
2b510 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
2b520 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
2b530 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
2b540 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
2b550 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
2b560 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
2b570 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
2b580 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
2b590 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20  E3_TEXT, not.** 
2b5a0 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a  SQLITE_TEXT..*/.
2b5b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
2b5c0 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e  NTEGER  1.#defin
2b5d0 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20  e SQLITE_FLOAT  
2b5e0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
2b5f0 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64  TE_BLOB     4.#d
2b600 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c  efine SQLITE_NUL
2b610 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53  L     5.#ifdef S
2b620 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64  QLITE_TEXT.# und
2b630 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
2b640 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51  else.# define SQ
2b650 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a  LITE_TEXT     3.
2b660 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53  #endif.#define S
2b670 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20  QLITE3_TEXT     
2b680 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  3../*.** CAPI3RE
2b690 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73  F: Result Values
2b6a0 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a   From A Query.**
2b6b0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75   KEYWORDS: {colu
2b6c0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2b6d0 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ons}.**.** These
2b6e0 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74   routines form t
2b6f0 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20  he "result set" 
2b700 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
2b710 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2b720 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
2b730 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67  ion about a sing
2b740 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
2b750 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75   current.** resu
2b760 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
2b770 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61  y.  ^In every ca
2b780 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
2b790 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
2b7a0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72  er.** to the [pr
2b7b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b7c0 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  ] that is being 
2b7d0 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
2b7e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a  sqlite3_stmt*].*
2b7f0 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  * that was retur
2b800 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2b810 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2b820 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
2b830 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74  riants).** and t
2b840 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2b850 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
2b860 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
2b870 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
2b880 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
2b890 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20   returned. ^The 
2b8a0 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
2b8b0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2b8c0 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20  t has the index 
2b8d0 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65  0..** ^The numbe
2b8e0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2b8f0 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62  the result can b
2b900 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
2b910 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
2b920 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a  olumn_count()]..
2b930 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
2b940 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
2b950 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f  not currently po
2b960 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72  int to a valid r
2b970 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a  ow, or if the.**
2b980 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73   column index is
2b990 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74   out of range, t
2b9a0 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  he result is und
2b9b0 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65  efined..** These
2b9c0 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e   routines may on
2b9d0 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
2b9e0 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
2b9f0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
2ba00 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2ba10 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  s returned [SQLI
2ba20 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74  TE_ROW] and neit
2ba30 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
2ba40 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71  reset()] nor [sq
2ba50 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2ba60 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  ] have been call
2ba70 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e  ed subsequently.
2ba80 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68  .** If any of th
2ba90 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2baa0 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
2bab0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2bac0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
2bad0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  inalize()] or af
2bae0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
2baf0 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
2bb00 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f  d.** something o
2bb10 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
2bb20 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75  E_ROW], the resu
2bb30 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2bb40 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65  d..** If [sqlite
2bb50 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
2bb60 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2bb70 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2bb80 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61  ize()].** are ca
2bb90 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66  lled from a diff
2bba0 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69  erent thread whi
2bbb0 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  le any of these 
2bbc0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
2bbd0 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68  pending, then th
2bbe0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2bbf0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
2bc00 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
2bc10 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e  mn_type() routin
2bc20 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
2bc30 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
2bc40 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65   | datatype code
2bc50 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61  ] for the initia
2bc60 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f  l data type.** o
2bc70 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c  f the result col
2bc80 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72  umn.  ^The retur
2bc90 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65  ned value is one
2bca0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45   of [SQLITE_INTE
2bcb0 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  GER],.** [SQLITE
2bcc0 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
2bcd0 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  _TEXT], [SQLITE_
2bce0 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BLOB], or [SQLIT
2bcf0 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61  E_NULL].  The va
2bd00 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
2bd10 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2bd20 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
2bd30 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
2bd40 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72  o type.** conver
2bd50 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72  sions have occur
2bd60 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64  red as described
2bd70 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61   below.  After a
2bd80 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2bd90 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72  ,.** the value r
2bda0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2bdb0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2bdc0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
2bdd0 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
2bde0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
2bdf0 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
2be00 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
2be10 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
2be20 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
2be30 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
2be40 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2be50 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
2be60 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
2be70 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
2be80 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
2be90 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2bea0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2beb0 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
2bec0 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
2bed0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2bee0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
2bef0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2bf00 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f  olumn_bytes() co
2bf10 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
2bf20 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e  ring to UTF-8 an
2bf30 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
2bf40 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2bf50 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
2bf60 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
2bf70 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
2bf80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2bf90 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  es() uses.** [sq
2bfa0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
2bfb0 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
2bfc0 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
2bfd0 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  -8 string and re
2bfe0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
2bff0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2c000 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
2c010 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2c020 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
2c030 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2c040 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  s() returns zero
2c050 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2c060 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
2c070 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
2c080 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
2c090 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2c0a0 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  6().** routine r
2c0b0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2c0c0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2c0d0 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
2c0e0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2c0f0 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20  sult is a UTF-8 
2c100 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
2c110 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2c120 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  s16() converts.*
2c130 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
2c140 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20  UTF-16 and then 
2c150 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2c160 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
2c170 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2c180 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
2c190 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
2c1a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2c1b0 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
2c1c0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
2c1d0 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
2c1e0 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73  ue to a UTF-16 s
2c1f0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2c200 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
2c210 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2c220 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2c230 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
2c240 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
2c250 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2c260 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
2c270 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65  **.** ^The value
2c280 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
2c290 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2c2a0 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b  tes()] and .** [
2c2b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c2c0 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74  ytes16()] do not
2c2d0 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
2c2e0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74  o terminators at
2c2f0 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74   the end.** of t
2c300 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72  he string.  ^For
2c310 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61   clarity: the va
2c320 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
2c330 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2c340 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
2c350 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2c360 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20  _bytes16()] are 
2c370 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
2c380 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
2c390 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75  ring, not the nu
2c3a0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
2c3b0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e  rs..**.** ^Strin
2c3c0 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  gs returned by s
2c3d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c3e0 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  xt() and sqlite3
2c3f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2c400 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20  ,.** even empty 
2c410 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77  strings, are alw
2c420 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
2c430 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ted.  ^The retur
2c440 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20  n.** value from 
2c450 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c460 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f  lob() for a zero
2c470 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20  -length BLOB is 
2c480 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
2c490 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63  **.** ^The objec
2c4a0 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  t returned by [s
2c4b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2c4c0 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20  lue()] is an.** 
2c4d0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2c4e0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2c4f0 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63  ct.  An unprotec
2c500 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2c510 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20  e object.** may 
2c520 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
2c530 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  h [sqlite3_bind_
2c540 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
2c550 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2c560 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
2c570 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2c580 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2c590 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
2c5a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2c5b0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
2c5c0 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
2c5d0 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
2c5e0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
2c5f0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
2c600 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
2c610 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2c620 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
2c630 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2c640 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  tes()], then the
2c650 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
2c660 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
2c670 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74  ese routines att
2c680 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
2c690 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20  the value where 
2c6a0 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46  appropriate.  ^F
2c6b0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
2c6c0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
2c6d0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
2c6e0 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
2c6f0 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
2c700 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
2c710 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
2c720 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
2c730 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
2c740 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
2c750 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e  utomatically.  ^
2c760 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  (The following t
2c770 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
2c780 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
2c790 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
2c7a0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
2c7b0 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
2c7c0 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
2c7d0 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
2c7e0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
2c7f0 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
2c800 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
2c810 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
2c820 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
2c830 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
2c840 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
2c850 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2c860 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2c870 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
2c880 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2c890 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
2c8a0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2c8b0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
2c8c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2c8d0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2c8e0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2c8f0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
2c900 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
2c910 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
2c920 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2c930 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
2c940 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
2c950 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
2c960 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2c970 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
2c980 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
2c990 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2c9a0 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
2c9b0 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
2c9c0 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
2c9d0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2c9e0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2c9f0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
2ca00 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65  om float to inte
2ca10 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
2ca20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
2ca30 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
2ca40 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
2ca50 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
2ca60 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2ca70 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2ca80 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54  d> Same as FLOAT
2ca90 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
2caa0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2cab0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2cac0 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  Use atoi().** <t
2cad0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2cae0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2caf0 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a  td> Use atof().*
2cb00 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2cb10 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2cb20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
2cb30 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
2cb40 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
2cb50 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
2cb60 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
2cb70 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  use atoi().** <t
2cb80 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
2cb90 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2cba0 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
2cbb0 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
2cbc0 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
2cbd0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
2cbe0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
2cbf0 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
2cc00 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
2cc10 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
2cc20 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
2cc30 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76  * The table abov
2cc40 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63  e makes referenc
2cc50 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20  e to standard C 
2cc60 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e  library function
2cc70 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20  s atoi().** and 
2cc80 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20  atof().  SQLite 
2cc90 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20  does not really 
2cca0 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69  use these functi
2ccb0 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73  ons.  It has its
2ccc0 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65  .** own equivale
2ccd0 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74  nt internal rout
2cce0 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28  ines.  The atoi(
2ccf0 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d  ) and atof() nam
2cd00 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69  es are.** used i
2cd10 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20  n the table for 
2cd20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61  brevity and beca
2cd30 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d  use they are fam
2cd40 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a  iliar to most.**
2cd50 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a   C programmers..
2cd60 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2cd70 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
2cd80 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
2cd90 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
2cda0 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
2cdb0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2cdc0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
2cdd0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2cde0 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
2cdf0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2ce00 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
2ce10 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20  idated..** Type 
2ce20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
2ce30 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
2ce40 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
2ce50 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
2ce60 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
2ce70 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
2ce80 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2ce90 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
2cea0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2ceb0 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20  _text() or.**   
2cec0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
2ced0 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
2cee0 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
2cef0 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
2cf00 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62  *      need to b
2cf10 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
2cf20 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  tring.</li>.** <
2cf30 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2cf40 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38  content is UTF-8
2cf50 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
2cf60 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2cf70 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
2cf80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2cf90 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
2cfa0 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
2cfb0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
2cfc0 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31  **      to UTF-1
2cfd0 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  6.</li>.** <li> 
2cfe0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2cff0 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
2d000 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
2d010 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
2d020 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
2d030 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
2d040 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
2d050 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
2d060 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
2d070 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a   to UTF-8.</li>.
2d080 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
2d090 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
2d0a0 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
2d0b0 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
2d0c0 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
2d0d0 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
2d0e0 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
2d0f0 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
2d100 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
2d110 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2d120 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
2d130 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
2d140 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c  r references wil
2d150 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
2d160 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
2d170 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
2d180 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
2d190 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
2d1a0 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
2d1b0 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a  ometimes they.**
2d1c0 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c   are not possibl
2d1d0 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
2d1e0 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
2d1f0 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
2d200 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ted..**.** The s
2d210 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73  afest and easies
2d220 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f  t to remember po
2d230 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b  licy is to invok
2d240 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
2d250 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  .** in one of th
2d260 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73  e following ways
2d270 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
2d280 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
2d290 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f  umn_text() follo
2d2a0 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
2d2b0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
2d2c0 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
2d2d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2d2e0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
2d2f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d300 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
2d310 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
2d320 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65  text16() followe
2d330 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2d340 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c  umn_bytes16()</l
2d350 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
2d360 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
2d370 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c  , you should cal
2d380 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
2d390 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69  _text(),.** sqli
2d3a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2d3b0 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ), or sqlite3_co
2d3c0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69  lumn_text16() fi
2d3d0 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65  rst to force the
2d3e0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20   result.** into 
2d3f0 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d  the desired form
2d400 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  at, then invoke 
2d410 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d420 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  ytes() or.** sql
2d430 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d440 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68  s16() to find th
2d450 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65  e size of the re
2d460 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69  sult.  Do not mi
2d470 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71  x calls.** to sq
2d480 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2d490 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  t() or sqlite3_c
2d4a0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74  olumn_blob() wit
2d4b0 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  h calls to.** sq
2d4c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2d4d0 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e  es16(), and do n
2d4e0 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20  ot mix calls to 
2d4f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2d500 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20  ext16().** with 
2d510 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2d520 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
2d530 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e  .**.** ^The poin
2d540 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
2d550 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
2d560 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
2d570 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
2d580 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
2d590 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
2d5a0 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
2d5b0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
2d5c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
2d5d0 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
2d5e0 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  d.  ^The memory 
2d5f0 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
2d600 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
2d610 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64  d BLOBs is freed
2d620 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
2d630 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70   Do <b>not</b> p
2d640 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
2d650 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71   returned.** [sq
2d660 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2d670 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  b()], [sqlite3_c
2d680 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65  olumn_text()], e
2d690 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  tc. into.** [sql
2d6a0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
2d6b0 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72  .** ^(If a memor
2d6c0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
2d6d0 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
2d6e0 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
2d6f0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
2d700 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
2d710 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
2d720 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
2d730 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
2d740 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
2d750 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
2d760 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
2d770 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
2d780 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
2d790 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
2d7a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
2d7b0 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
2d7c0 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
2d7d0 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74  MEM].)^.*/.const
2d7e0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2d7f0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
2d800 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2d810 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
2d820 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
2d830 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2d840 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
2d850 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2d860 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2d870 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75  , int iCol);.dou
2d880 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
2d890 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
2d8a0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2d8b0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2d8c0 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
2d8d0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2d8e0 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ol);.sqlite3_int
2d8f0 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
2d900 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
2d910 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2d920 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
2d930 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2d940 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
2d950 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2d960 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ol);.const void 
2d970 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2d980 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
2d990 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2d9a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2d9b0 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
2d9c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2d9d0 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  );.sqlite3_value
2d9e0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2d9f0 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
2da00 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2da10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2da20 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
2da30 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
2da40 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bject.**.** ^The
2da50 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2da60 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
2da70 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
2da80 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2da90 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20  tement]..** ^If 
2daa0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2dab0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68  evaluation of th
2dac0 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f  e statement enco
2dad0 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72  untered no error
2dae0 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73  s.** or if the s
2daf0 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65  tatement is neve
2db00 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64  r been evaluated
2db10 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66  , then sqlite3_f
2db20 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e  inalize() return
2db30 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20  s.** SQLITE_OK. 
2db40 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2db50 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
2db60 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66  of statement S f
2db70 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73  ailed, then.** s
2db80 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2db90 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61  S) returns the a
2dba0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
2dbb0 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  r code] or.** [e
2dbc0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
2dbd0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
2dbe0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2dbf0 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  (S) routine can 
2dc00 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
2dc10 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a   point during.**
2dc20 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20   the life cycle 
2dc30 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
2dc40 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65  tement] S:.** be
2dc50 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53  fore statement S
2dc60 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74   is ever evaluat
2dc70 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65  ed, after.** one
2dc80 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74   or more calls t
2dc90 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
2dca0 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e  ()], or after an
2dcb0 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71  y call.** to [sq
2dcc0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
2dcd0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
2dce0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73  her or not the s
2dcf0 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20  tatement has.** 
2dd00 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
2dd10 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f  ion..**.** ^Invo
2dd20 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e  king sqlite3_fin
2dd30 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c  alize() on a NUL
2dd40 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68  L pointer is a h
2dd50 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
2dd60 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
2dd70 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69  tion must finali
2dd80 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72  ze every [prepar
2dd90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
2dda0 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a   order to avoid.
2ddb0 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b  ** resource leak
2ddc0 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65  s.  It is a grie
2ddd0 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74  vous error for t
2dde0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
2ddf0 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20  o try to use.** 
2de00 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
2de10 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
2de20 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
2de30 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20  .  Any use of a 
2de40 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
2de50 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
2de60 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
2de70 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20  d can result in 
2de80 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a  undefined and.**
2de90 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68   undesirable beh
2dea0 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65  avior such as se
2deb0 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70  gfaults and heap
2dec0 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
2ded0 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
2dee0 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
2def0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2df00 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
2df10 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
2df20 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
2df30 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2df40 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
2df50 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
2df60 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
2df70 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
2df80 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
2df90 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
2dfa0 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
2dfb0 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  xecuted..** ^Any
2dfc0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
2dfd0 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
2dfe0 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
2dff0 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
2e000 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
2e010 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
2e020 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
2e030 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
2e040 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
2e050 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
2e060 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
2e070 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
2e080 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
2e090 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
2e0a0 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
2e0b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2e0c0 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74  ent] S.** back t
2e0d0 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
2e0e0 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
2e0f0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
2e100 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2e110 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2e120 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
2e130 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e140 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
2e150 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
2e160 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
2e170 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   or if [sqlite3_
2e180 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76  step(S)] has nev
2e190 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63  er before been c
2e1a0 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74  alled on S,.** t
2e1b0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
2e1c0 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
2e1d0 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
2e1e0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2e1f0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2e200 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2e210 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
2e220 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2e230 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
2e240 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73  rror, then.** [s
2e250 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2e260 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
2e270 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
2e280 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
2e290 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2e2a0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  S)] interface do
2e2b0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
2e2c0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61  e values.** of a
2e2d0 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ny [sqlite3_bind
2e2e0 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20  _blob|bindings] 
2e2f0 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
2e300 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
2e310 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
2e320 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
2e330 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2e340 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
2e350 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
2e360 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b  L Functions.** K
2e370 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
2e380 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
2e390 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
2e3a0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
2e3b0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2e3c0 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
2e3d0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
2e3e0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2e3f0 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions}.**.** ^Th
2e400 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  ese functions (c
2e410 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
2e420 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
2e430 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
2e440 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
2e450 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
2e460 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
2e470 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
2e480 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
2e490 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
2e4a0 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
2e4b0 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f  gregates.  The o
2e4c0 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20  nly differences 
2e4d0 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65  between.** these
2e4e0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68   routines are th
2e4f0 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  e text encoding 
2e500 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20  expected for.** 
2e510 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
2e520 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f  eter (the name o
2e530 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62  f the function b
2e540 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a  eing created).**
2e550 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63   and the presenc
2e560 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20  e or absence of 
2e570 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  a destructor cal
2e580 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65  lback for.** the
2e590 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
2e5a0 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  a pointer..**.**
2e5b0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
2e5c0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61  meter is the [da
2e5d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e5e0 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  n] to which the 
2e5f0 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
2e600 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20  is to be added. 
2e610 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74   ^If an applicat
2e620 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68  ion uses more th
2e630 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a  an one database.
2e640 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
2e650 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  en application-d
2e660 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2e670 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64  ions must be add
2e680 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61  ed.** to each da
2e690 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e6a0 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  n separately..**
2e6b0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
2e6c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2e6d0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
2e6e0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2e6f0 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65  created or.** re
2e700 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c  defined.  ^The l
2e710 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d  ength of the nam
2e720 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20  e is limited to 
2e730 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55  255 bytes in a U
2e740 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e  TF-8.** represen
2e750 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76  tation, exclusiv
2e760 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65  e of the zero-te
2e770 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65  rminator.  ^Note
2e780 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a   that the name.*
2e790 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69  * length limit i
2e7a0 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73  s in UTF-8 bytes
2e7b0 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73  , not characters
2e7c0 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65   nor UTF-16 byte
2e7d0 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74  s.  .** ^Any att
2e7e0 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
2e7f0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
2e800 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20   longer name.** 
2e810 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b  will result in [
2e820 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62  SQLITE_MISUSE] b
2e830 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a  eing returned..*
2e840 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
2e850 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29  parameter (nArg)
2e860 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
2e870 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
2e880 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
2e890 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2e8a0 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20  gate takes. ^If 
2e8b0 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
2e8c0 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53  s -1, then the S
2e8d0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
2e8e0 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
2e8f0 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
2e900 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74  of arguments bet
2e910 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c  ween 0 and the l
2e920 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b  imit.** set by [
2e930 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
2e940 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
2e950 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66  CTION_ARG]).  If
2e960 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
2e970 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
2e980 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
2e990 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e  er than 127 then
2e9a0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2e9b0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
2e9c0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
2e9d0 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
2e9e0 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
2e9f0 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  what.** [SQLITE_
2ea00 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
2ea10 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
2ea20 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
2ea30 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
2ea40 65 74 65 72 73 2e 20 20 45 76 65 72 79 20 53 51  eters.  Every SQ
2ea50 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
2ea60 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62  mentation must b
2ea70 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a  e able to work.*
2ea80 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54  * with UTF-8, UT
2ea90 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31  F-16le, or UTF-1
2eaa0 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69  6be.  But some i
2eab0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
2eac0 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66  ay be.** more ef
2ead0 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65  ficient with one
2eae0 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61   encoding than a
2eaf0 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70  nother.  ^An app
2eb00 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20  lication may.** 
2eb10 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
2eb20 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2eb30 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61   or sqlite3_crea
2eb40 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20  te_function16() 
2eb50 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65  multiple.** time
2eb60 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
2eb70 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74  function but wit
2eb80 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75  h different valu
2eb90 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a  es of eTextRep..
2eba0 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c  ** ^When multipl
2ebb0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2ebc0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
2ebd0 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
2ebe0 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
2ebf0 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
2ec00 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
2ec10 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
2ec20 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
2ec30 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65  ion..** If there
2ec40 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c   is only a singl
2ec50 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2ec60 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20   which does not 
2ec70 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a  care what text.*
2ec80 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  * encoding is us
2ec90 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ed, then the fou
2eca0 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rth argument sho
2ecb0 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  uld be [SQLITE_A
2ecc0 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  NY]..**.** ^(The
2ecd0 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
2ece0 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
2ecf0 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69   pointer.  The i
2ed00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2ed10 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
2ed20 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73   can gain access
2ed30 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72   to this pointer
2ed40 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2ed50 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a  user_data()].)^.
2ed60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68  **.** ^The sixth
2ed70 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69  , seventh and ei
2ed80 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c  ghth parameters,
2ed90 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e   xFunc, xStep an
2eda0 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a  d xFinal, are.**
2edb0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c   pointers to C-l
2edc0 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e  anguage function
2edd0 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
2ede0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2edf0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2ee00 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c  e. ^A scalar SQL
2ee10 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
2ee20 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
2ee30 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e  tion of the xFun
2ee40 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e  c.** callback on
2ee50 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ly; NULL pointer
2ee60 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  s must be passed
2ee70 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e   as the xStep an
2ee80 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61  d xFinal.** para
2ee90 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72  meters. ^An aggr
2eea0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2eeb0 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
2eec0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2eed0 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46   xStep.** and xF
2eee0 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f  inal and NULL po
2eef0 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61  inter must be pa
2ef00 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20  ssed for xFunc. 
2ef10 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78  ^To delete an ex
2ef20 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75  isting.** SQL fu
2ef30 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
2ef40 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70  ate, pass NULL p
2ef50 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20  ointers for all 
2ef60 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  three function.*
2ef70 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a  * callbacks..**.
2ef80 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74  ** ^(If the nint
2ef90 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2efa0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2efb0 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e  nction_v2() is n
2efc0 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e  ot NULL,.** then
2efd0 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f   it is destructo
2efe0 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63  r for the applic
2eff0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
2f000 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74  er. .** The dest
2f010 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65  ructor is invoke
2f020 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74  d when the funct
2f030 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20  ion is deleted, 
2f040 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a  either by being.
2f050 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72  ** overloaded or
2f060 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
2f070 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
2f080 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20  oses.)^.** ^The 
2f090 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c  destructor is al
2f0a0 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68  so invoked if th
2f0b0 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  e call to.** sql
2f0c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2f0d0 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e  tion_v2() fails.
2f0e0 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65  .** ^When the de
2f0f0 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
2f100 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70  k of the tenth p
2f110 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f  arameter is invo
2f120 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61  ked, it.** is pa
2f130 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72  ssed a single ar
2f140 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
2f150 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70  a copy of the ap
2f160 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a  plication data .
2f170 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  ** pointer which
2f180 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70   was the fifth p
2f190 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2f1a0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2f1b0 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  ion_v2()..**.** 
2f1c0 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64  ^It is permitted
2f1d0 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c   to register mul
2f1e0 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
2f1f0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2f200 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77  e.** functions w
2f210 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
2f220 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65  e but with eithe
2f230 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62  r differing numb
2f240 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65  ers of.** argume
2f250 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67  nts or differing
2f260 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
2f270 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c  encodings.  ^SQL
2f280 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
2f290 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
2f2a0 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f  on that most clo
2f2b0 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65  sely matches the
2f2c0 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68   way in which th
2f2d0 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  e.** SQL functio
2f2e0 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66  n is used.  ^A f
2f2f0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2f300 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
2f310 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41  n-negative.** nA
2f320 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rg parameter is 
2f330 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74  a better match t
2f340 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69  han a function i
2f350 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
2f360 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65  th.** a negative
2f370 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74   nArg.  ^A funct
2f380 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72  ion where the pr
2f390 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
2f3a0 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73  oding.** matches
2f3b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
2f3c0 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74  coding is a bett
2f3d0 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e  er.** match than
2f3e0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
2f3f0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69  e the encoding i
2f400 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a  s different.  .*
2f410 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68  * ^A function wh
2f420 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
2f430 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62   difference is b
2f440 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61  etween UTF16le a
2f450 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73  nd UTF16be.** is
2f460 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20   a closer match 
2f470 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
2f480 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
2f490 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
2f4a0 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38  .** between UTF8
2f4b0 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a   and UTF16..**.*
2f4c0 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63  * ^Built-in func
2f4d0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65  tions may be ove
2f4e0 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61  rloaded by new a
2f4f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2f500 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  ed functions..**
2f510 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74  .** ^An applicat
2f520 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2f530 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
2f540 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a  d to call other.
2f550 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
2f560 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20  aces.  However, 
2f570 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20  such calls must 
2f580 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65  not.** close the
2f590 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2f5a0 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a  tion nor finaliz
2f5b0 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70  e or reset the p
2f5c0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
2f5d0 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68  ment in which th
2f5e0 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  e function is ru
2f5f0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nning..*/.int sq
2f600 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2f610 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
2f620 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
2f630 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
2f640 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
2f650 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
2f660 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
2f670 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
2f680 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2f690 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2f6a0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
2f6b0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
2f6c0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2f6d0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2f6e0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
2f6f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
2f700 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
2f710 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
2f720 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
2f730 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
2f740 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
2f750 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
2f760 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
2f770 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
2f780 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
2f790 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2f7a0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2f7b0 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
2f7c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2f7d0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2f7e0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
2f7f0 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
2f800 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
2f810 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2f820 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ction_v2(.  sqli
2f830 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
2f840 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
2f850 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
2f860 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
2f870 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
2f880 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
2f890 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2f8a0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2f8b0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2f8c0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
2f8d0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2f8e0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2f8f0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
2f900 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2f910 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
2f920 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  oy)(void*).);../
2f930 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
2f940 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a  ext Encodings.**
2f950 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
2f960 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65  nt define intege
2f970 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70  r codes that rep
2f980 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f  resent the vario
2f990 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  us.** text encod
2f9a0 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62  ings supported b
2f9b0 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  y SQLite..*/.#de
2f9c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38  fine SQLITE_UTF8
2f9d0 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
2f9e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
2f9f0 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65  6LE        2.#de
2fa00 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
2fa10 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65  6BE        3.#de
2fa20 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
2fa30 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20  6          4    
2fa40 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79  /* Use native by
2fa50 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66  te order */.#def
2fa60 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20  ine SQLITE_ANY  
2fa70 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f            5    /
2fa80 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
2fa90 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a  _function only *
2faa0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2fab0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20  _UTF16_ALIGNED  
2fac0 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  8    /* sqlite3_
2fad0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2fae0 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   only */../*.** 
2faf0 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63  CAPI3REF: Deprec
2fb00 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ated Functions.*
2fb10 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a  * DEPRECATED.**.
2fb20 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
2fb30 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74  ns are [deprecat
2fb40 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74  ed].  In order t
2fb50 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61  o maintain.** ba
2fb60 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
2fb70 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72  ility with older
2fb80 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e   code, these fun
2fb90 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
2fba0 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72  .** to be suppor
2fbb0 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ted.  However, n
2fbc0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
2fbd0 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20  should avoid.** 
2fbe0 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65  the use of these
2fbf0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20   functions.  To 
2fc00 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70  help encourage p
2fc10 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a  eople to avoid.*
2fc20 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75  * using these fu
2fc30 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20  nctions, we are 
2fc40 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c  not going to tel
2fc50 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20  l you what they 
2fc60 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  do..*/.#ifndef S
2fc70 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45  QLITE_OMIT_DEPRE
2fc80 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50  CATED.SQLITE_DEP
2fc90 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2fca0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2fcb0 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  unt(sqlite3_cont
2fcc0 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  ext*);.SQLITE_DE
2fcd0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
2fce0 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c  ite3_expired(sql
2fcf0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
2fd00 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
2fd10 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73  nt sqlite3_trans
2fd20 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  fer_bindings(sql
2fd30 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69  ite3_stmt*, sqli
2fd40 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
2fd50 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
2fd60 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
2fd70 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
2fd80 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2fd90 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74  D void sqlite3_t
2fda0 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f  hread_cleanup(vo
2fdb0 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  id);.SQLITE_DEPR
2fdc0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2fdd0 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28  e3_memory_alarm(
2fde0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
2fdf0 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29  lite3_int64,int)
2fe00 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  ,void*,sqlite3_i
2fe10 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt64);.#endif../
2fe20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2fe30 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e  btaining SQL Fun
2fe40 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20  ction Parameter 
2fe50 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  Values.**.** The
2fe60 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c   C-language impl
2fe70 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51  ementation of SQ
2fe80 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
2fe90 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a  aggregates uses.
2fea0 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69  ** this set of i
2feb0 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
2fec0 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
2fed0 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73  parameter values
2fee0 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74   on.** the funct
2fef0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
2ff00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e  ..**.** The xFun
2ff10 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75  c (for scalar fu
2ff20 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65  nctions) or xSte
2ff30 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65  p (for aggregate
2ff40 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  s) parameters.**
2ff50 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
2ff60 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
2ff70 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
2ff80 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2ff90 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c  ].** define call
2ffa0 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65  backs that imple
2ffb0 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
2ffc0 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
2ffd0 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72  gates..** The 3r
2ffe0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
2fff0 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69  hese callbacks i
30000 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
30010 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72  inters to.** [pr
30020 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
30030 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20  value] objects. 
30040 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73   There is one [s
30050 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
30060 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ject for.** each
30070 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
30080 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20  e SQL function. 
30090 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
300a0 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65  are used to.** e
300b0 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72  xtract values fr
300c0 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
300d0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
300e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
300f0 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77  ines work only w
30100 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ith [protected s
30110 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
30120 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74  jects..** Any at
30130 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
30140 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61  se routines on a
30150 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
30160 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
30170 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20   object results 
30180 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
30190 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  avior..**.** ^Th
301a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
301b0 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
301c0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63  corresponding [c
301d0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
301e0 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70  ctions].** excep
301f0 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f  t that  these ro
30200 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
30210 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
30220 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
30230 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
30240 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
30250 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
30260 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
30270 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
30280 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
30290 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
302a0 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
302b0 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31  extracts a UTF-1
302c0 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74  6 string.** in t
302d0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f  he native byte-o
302e0 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
302f0 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a   machine.  ^The.
30300 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
30310 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20  _text16be() and 
30320 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
30330 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61  xt16le() interfa
30340 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55  ces.** extract U
30350 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73  TF-16 strings as
30360 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
30370 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
30380 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
30390 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
303a0 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
303b0 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
303c0 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
303d0 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
303e0 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
303f0 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
30400 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
30410 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
30420 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
30430 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
30440 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
30450 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
30460 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
30470 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
30480 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
30490 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
304a0 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75  rds, if the valu
304b0 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
304c0 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
304d0 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
304e0 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
304f0 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74  s performed.  Ot
30500 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
30510 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a  rsion occurs..**
30520 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54   The [SQLITE_INT
30530 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
30540 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
30550 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
30560 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
30570 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
30580 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
30590 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
305a0 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
305b0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
305c0 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
305d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
305e0 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
305f0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
30600 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
30610 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
30620 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
30630 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
30640 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
30650 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
30660 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
30670 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
30680 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
30690 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
306a0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
306b0 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
306c0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
306d0 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
306e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
306f0 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
30700 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
30710 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
30720 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
30730 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
30740 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
30750 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
30760 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
30770 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
30780 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
30790 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
307a0 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  *);.double sqlit
307b0 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
307c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
307d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
307e0 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
307f0 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  alue*);.sqlite3_
30800 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61  int64 sqlite3_va
30810 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
30820 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
30830 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
30840 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
30850 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
30860 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
30870 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
30880 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
30890 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
308a0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
308b0 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
308c0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
308d0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
308e0 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
308f0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
30900 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
30910 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
30920 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
30930 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
30940 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
30950 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
30960 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
30970 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
30980 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49   Context.**.** I
30990 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
309a0 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
309b0 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
309c0 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f  is.** routine to
309d0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
309e0 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
309f0 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ir state..**.** 
30a00 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
30a10 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
30a20 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
30a30 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  N) routine is ca
30a40 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70  lled .** for a p
30a50 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67  articular aggreg
30a60 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51  ate function, SQ
30a70 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  Lite.** allocate
30a80 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a  s N of memory, z
30a90 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d  eroes out that m
30aa0 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
30ab0 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
30ac0 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72  to the new memor
30ad0 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  y. ^On second an
30ae0 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
30af0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
30b00 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
30b10 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d  xt() for the sam
30b20 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
30b30 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a  tion instance,.*
30b40 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  * the same buffe
30b50 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
30b60 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  Sqlite3_aggregat
30b70 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e  e_context() is n
30b80 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  ormally.** calle
30b90 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
30ba0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
30bb0 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b  e xStep callback
30bc0 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a   and then one.**
30bd0 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20   last time when 
30be0 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
30bf0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ack is invoked. 
30c00 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20   ^(When no rows 
30c10 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72  match.** an aggr
30c20 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65  egate query, the
30c30 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63   xStep() callbac
30c40 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  k of the aggrega
30c50 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69  te function.** i
30c60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
30c70 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e   never called an
30c80 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61  d xFinal() is ca
30c90 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63  lled exactly onc
30ca0 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63  e..** In those c
30cb0 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67  ases, sqlite3_ag
30cc0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
30cd0 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
30ce0 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72  d for the.** fir
30cf0 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74  st time from wit
30d00 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a  hin xFinal().)^.
30d10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
30d20 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
30d30 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
30d40 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
30d50 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73   pointer if N is
30d60 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  .** less than or
30d70 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f   equal to zero o
30d80 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r if a memory al
30d90 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63  locate error occ
30da0 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  urs..**.** ^(The
30db0 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65   amount of space
30dc0 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
30dd0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
30de0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a  context(C,N) is.
30df0 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  ** determined by
30e00 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
30e10 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73   on first succes
30e20 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e  sful call.  Chan
30e30 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ging the.** valu
30e40 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71  e of N in subseq
30e50 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
30e60 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
30e70 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a  ontext() within.
30e80 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  ** the same aggr
30e90 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
30ea0 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74  nstance will not
30eb0 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f   resize the memo
30ec0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
30ed0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
30ee0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
30ef0 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  frees the memory
30f00 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a   allocated by .*
30f10 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
30f20 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68  ate_context() wh
30f30 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65  en the aggregate
30f40 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73   query concludes
30f50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
30f60 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
30f70 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
30f80 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
30f90 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63  ntext | SQL func
30fa0 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68  tion context] th
30fb0 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  at is the first 
30fc0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
30fd0 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69  the xStep or xFi
30fe0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  nal callback rou
30ff0 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  tine that implem
31000 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61  ents the aggrega
31010 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a  te.** function..
31020 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
31030 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
31040 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
31050 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
31060 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
31070 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
31080 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
31090 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
310a0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
310b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
310c0 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
310d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
310e0 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
310f0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ions.**.** ^The 
31100 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
31110 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
31120 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
31130 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
31140 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65  hat was the pUse
31150 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20  rData parameter 
31160 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (the 5th paramet
31170 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
31180 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
31190 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
311a0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
311b0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
311c0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
311d0 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
311e0 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
311f0 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
31200 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
31210 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
31220 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
31230 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
31240 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
31250 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
31260 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ed function is r
31270 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
31280 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  *sqlite3_user_da
31290 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
312a0 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
312b0 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
312c0 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46  Connection For F
312d0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
312e0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
312f0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
31300 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
31310 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
31320 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
31330 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
31340 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
31350 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
31360 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
31370 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
31380 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
31390 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
313a0 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
313b0 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
313c0 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
313d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
313e0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
313f0 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
31400 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
31410 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  andle(sqlite3_co
31420 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
31430 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
31440 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
31450 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c  a.**.** The foll
31460 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69  owing two functi
31470 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20  ons may be used 
31480 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  by scalar SQL fu
31490 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73  nctions to.** as
314a0 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61  sociate metadata
314b0 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76   with argument v
314c0 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61  alues. If the sa
314d0 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73  me value is pass
314e0 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c  ed to.** multipl
314f0 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  e invocations of
31500 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75   the same SQL fu
31510 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75  nction during qu
31520 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75  ery execution, u
31530 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72  nder.** some cir
31540 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61  cumstances the a
31550 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61  ssociated metada
31560 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72  ta may be preser
31570 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a  ved. This may.**
31580 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78   be used, for ex
31590 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20  ample, to add a 
315a0 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69  regular-expressi
315b0 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c  on matching scal
315c0 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20  ar.** function. 
315d0 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72  The compiled ver
315e0 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75  sion of the regu
315f0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69  lar expression i
31600 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d  s stored as.** m
31610 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74  etadata associat
31620 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20  ed with the SQL 
31630 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
31640 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
31650 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72  ession.** patter
31660 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  n.  The compiled
31670 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
31680 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65  ion can be reuse
31690 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  d on multiple.**
316a0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
316b0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
316c0 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72  n so that the or
316d0 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73  iginal pattern s
316e0 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tring.** does no
316f0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63  t need to be rec
31700 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20  ompiled on each 
31710 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  invocation..**.*
31720 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
31730 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
31740 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
31750 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
31760 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
31770 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71  ciated by the sq
31780 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
31790 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  a() function wit
317a0 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  h the Nth argume
317b0 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74  nt.** value to t
317c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
317d0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
317e0 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61   ^If no metadata
317f0 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a   has been ever.*
31800 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74  * been set for t
31810 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20  he Nth argument 
31820 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c  of the function,
31830 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65   or if the corre
31840 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63  sponding.** func
31850 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68  tion parameter h
31860 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65  as changed since
31870 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77   the meta-data w
31880 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20  as set,.** then 
31890 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
318a0 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20  ata() returns a 
318b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
318c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
318d0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _set_auxdata() i
318e0 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74  nterface saves t
318f0 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70  he metadata.** p
31900 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73  ointed to by its
31910 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61   3rd parameter a
31920 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66  s the metadata f
31930 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61  or the N-th.** a
31940 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  rgument of the a
31950 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
31960 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75  ed function.  Su
31970 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
31980 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74  s to sqlite3_get
31990 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74  _auxdata() might
319a0 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74   return this dat
319b0 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  a, if it has.** 
319c0 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79  not been destroy
319d0 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73  ed..** ^If it is
319e0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74   not NULL, SQLit
319f0 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
31a00 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
31a10 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62  function given b
31a20 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  y the 4th parame
31a30 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  ter to sqlite3_s
31a40 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a  et_auxdata() on.
31a50 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  ** the metadata 
31a60 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  when the corresp
31a70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  onding function 
31a80 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65  parameter change
31a90 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65  s.** or when the
31aa0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63   SQL statement c
31ab0 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65  ompletes, whiche
31ac0 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e  ver comes first.
31ad0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73  .**.** SQLite is
31ae0 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68   free to call th
31af0 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64  e destructor and
31b00 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f   drop metadata o
31b10 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74  n any.** paramet
31b20 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69  er of any functi
31b30 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20  on at any time. 
31b40 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61   ^The only guara
31b50 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20  ntee is that.** 
31b60 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77  the destructor w
31b70 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65  ill be called be
31b80 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74  fore the metadat
31b90 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a  a is dropped..**
31ba0 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63  .** ^(In practic
31bb0 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70  e, metadata is p
31bc0 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e  reserved between
31bd0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20   function calls 
31be0 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f  for.** expressio
31bf0 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73  ns that are cons
31c00 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20  tant at compile 
31c10 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75  time. This inclu
31c20 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76  des literal.** v
31c30 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d  alues and [param
31c40 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  eters].)^.**.** 
31c50 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
31c60 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
31c70 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
31c80 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
31c90 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
31ca0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
31cb0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74  oid *sqlite3_get
31cc0 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
31cd0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
31ce0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
31cf0 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  set_auxdata(sqli
31d00 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
31d10 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64  t N, void*, void
31d20 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a   (*)(void*));...
31d30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31d40 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69  Constants Defini
31d50 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72  ng Special Destr
31d60 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a  uctor Behavior.*
31d70 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73  *.** These are s
31d80 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f  pecial values fo
31d90 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  r the destructor
31da0 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
31db0 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e  in as the.** fin
31dc0 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72  al argument to r
31dd0 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
31de0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
31df0 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64  b()].  ^If the d
31e00 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67  estructor.** arg
31e10 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f  ument is SQLITE_
31e20 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73  STATIC, it means
31e30 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
31e40 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e  t pointer is con
31e50 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c  stant.** and wil
31e60 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20  l never change. 
31e70 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65   It does not nee
31e80 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65  d to be destroye
31e90 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49  d.  ^The.** SQLI
31ea0 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c  TE_TRANSIENT val
31eb0 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ue means that th
31ec0 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c  e content will l
31ed0 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a  ikely change in.
31ee0 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75  ** the near futu
31ef0 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69  re and that SQLi
31f00 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69  te should make i
31f10 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
31f20 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
31f30 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74  ntent before ret
31f40 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  urning..**.** Th
31f50 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63  e typedef is nec
31f60 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61  essary to work a
31f70 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69  round problems i
31f80 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b  n certain.** C++
31f90 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65   compilers.  See
31fa0 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a   ticket #2191..*
31fb0 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  /.typedef void (
31fc0 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  *sqlite3_destruc
31fd0 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29  tor_type)(void*)
31fe0 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
31ff0 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73  _STATIC      ((s
32000 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
32010 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e  r_type)0).#defin
32020 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  e SQLITE_TRANSIE
32030 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64  NT   ((sqlite3_d
32040 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d  estructor_type)-
32050 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  1)../*.** CAPI3R
32060 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20  EF: Setting The 
32070 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c  Result Of An SQL
32080 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20   Function.**.** 
32090 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
320a0 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
320b0 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
320c0 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
320d0 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
320e0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
320f0 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
32100 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
32110 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
32120 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
32130 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
32140 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
32150 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
32160 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
32170 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
32180 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72  ch like the [par
32190 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20  ameter binding] 
321a0 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e  family of.** fun
321b0 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62  ctions used to b
321c0 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
321d0 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
321e0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
321f0 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
32200 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d  o the [SQL param
32210 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74  eter] documentat
32220 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
32230 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
32240 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
32250 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
32260 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
32270 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
32280 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
32290 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
322a0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f  on to be the BLO
322b0 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20  B whose content 
322c0 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f  is pointed.** to
322d0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
322e0 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69  arameter and whi
322f0 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f  ch is N bytes lo
32300 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  ng where N is th
32310 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
32320 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
32330 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32340 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72  zeroblob() inter
32350 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65  faces set the re
32360 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
32370 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
32380 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
32390 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e  e a BLOB contain
323a0 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20  ing all zero.** 
323b0 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65  bytes and N byte
323c0 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65  s in size, where
323d0 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20   N is the value 
323e0 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  of the 2nd param
323f0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
32400 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32410 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
32420 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
32430 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
32440 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
32450 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
32460 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
32470 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
32480 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
32490 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
324a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
324b0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
324c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
324d0 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f  rror16() functio
324e0 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20  ns.** cause the 
324f0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20  implemented SQL 
32500 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f  function to thro
32510 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a  w an exception..
32520 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
32530 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  the string point
32540 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20  ed to by the.** 
32550 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
32560 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32570 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74  error() or sqlit
32580 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
32590 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65  6().** as the te
325a0 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d  xt of an error m
325b0 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65  essage.  ^SQLite
325c0 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
325d0 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
325e0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
325f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32600 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53  r() as UTF-8. ^S
32610 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72  QLite.** interpr
32620 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66  ets the string f
32630 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
32640 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20  lt_error16() as 
32650 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
32660 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20  .** byte order. 
32670 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
32680 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
32690 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
326a0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
326b0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
326c0 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
326d0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
326e0 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
326f0 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
32700 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
32710 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
32720 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
32730 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
32740 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
32750 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a  lt_error() or.**
32760 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32770 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e  error16() is non
32780 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53  -negative then S
32790 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74  QLite takes that
327a0 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28   many.** bytes (
327b0 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
327c0 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
327d0 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72  ameter as the er
327e0 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20  ror message..** 
327f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
32800 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
32810 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
32820 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
32830 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
32840 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
32850 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
32860 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
32870 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
32880 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
32890 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
328a0 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
328b0 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
328c0 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
328d0 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e  thout harm..** ^
328e0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
328f0 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20  lt_error_code() 
32900 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73  function changes
32910 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a   the error code.
32920 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  ** returned by S
32930 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c  QLite as a resul
32940 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e  t of an error in
32950 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42   a function.  ^B
32960 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68  y default,.** th
32970 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  e error code is 
32980 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e  SQLITE_ERROR.  ^
32990 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
329a0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  l to sqlite3_res
329b0 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
329c0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
329d0 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74  _error16() reset
329e0 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
329f0 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   to SQLITE_ERROR
32a00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
32a10 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32a20 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72  r_toobig() inter
32a30 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
32a40 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a  te to throw an.*
32a50 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69  * error indicati
32a60 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67  ng that a string
32a70 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20   or BLOB is too 
32a80 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e  long to represen
32a90 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
32aa0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32ab0 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72  or_nomem() inter
32ac0 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
32ad0 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a  te to throw an.*
32ae0 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69  * error indicati
32af0 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79  ng that a memory
32b00 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
32b10 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
32b20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
32b30 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  t() interface se
32b40 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
32b50 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
32b60 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
32b70 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
32b80 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e   the 32-bit sign
32b90 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
32ba0 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
32bb0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
32bc0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
32bd0 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e  esult_int64() in
32be0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
32bf0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
32c00 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
32c10 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
32c20 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36  tion to be the 6
32c30 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
32c40 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
32c50 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
32c60 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
32c70 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
32c80 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66  lt_null() interf
32c90 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
32ca0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
32cb0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
32cc0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
32cd0 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a   to be NULL..**.
32ce0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
32cf0 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73  result_text(), s
32d00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
32d10 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  xt16(),.** sqlit
32d20 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
32d30 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  le(), and sqlite
32d40 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
32d50 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
32d60 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e  * set the return
32d70 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70   value of the ap
32d80 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
32d90 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
32da0 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e  .** a text strin
32db0 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65  g which is repre
32dc0 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c  sented as UTF-8,
32dd0 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
32de0 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54  yte order,.** UT
32df0 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69  F-16 little endi
32e00 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
32e10 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g endian, respec
32e20 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69  tively..** ^SQLi
32e30 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78  te takes the tex
32e40 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68  t result from th
32e50 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72  e application fr
32e60 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61  om.** the 2nd pa
32e70 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73  rameter of the s
32e80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
32e90 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  xt* interfaces..
32ea0 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
32eb0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
32ec0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
32ed0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
32ee0 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
32ef0 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
32f00 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72  s result text fr
32f10 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
32f20 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20  eter.** through 
32f30 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
32f40 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
32f50 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
32f60 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
32f70 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
32f80 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
32f90 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
32fa0 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73  en as many bytes
32fb0 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
32fc0 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a  ) of the text.**
32fd0 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
32fe0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
32ff0 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68   are taken as th
33000 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
33010 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f  fined.** functio
33020 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68  n result.  If th
33030 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
33040 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
33050 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74   then it.** must
33060 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66   be the byte off
33070 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72  set into the str
33080 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e 55  ing where the NU
33090 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75  L terminator wou
330a0 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20  ld.** appear if 
330b0 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65  the string where
330c0 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e   NUL terminated.
330d0 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61    If any NUL cha
330e0 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a  racters occur.**
330f0 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61   in the string a
33100 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 20  t a byte offset 
33110 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 61  that is less tha
33120 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  n the value of t
33130 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65  he 3rd.** parame
33140 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ter, then the re
33150 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77  sulting string w
33160 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65  ill contain embe
33170 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68  dded NULs and th
33180 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65  e.** result of e
33190 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61  xpressions opera
331a0 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20  ting on strings 
331b0 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55  with embedded NU
331c0 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  Ls is undefined.
331d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
331e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
331f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33200 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
33210 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
33220 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20  esult_blob is a 
33230 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
33240 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61  , then SQLite ca
33250 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63  lls that.** func
33260 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74  tion as the dest
33270 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65  ructor on the te
33280 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
33290 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a  t when it has.**
332a0 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
332b0 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
332c0 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
332d0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
332e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
332f0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20  * interfaces or 
33300 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  to.** sqlite3_re
33310 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
33320 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
33330 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  t SQLITE_STATIC,
33340 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20   then SQLite.** 
33350 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
33360 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
33370 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74  sult is in const
33380 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ant space and do
33390 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74  es not.** copy t
333a0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
333b0 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20  e parameter nor 
333c0 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f  call a destructo
333d0 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74  r on the content
333e0 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20  .** when it has 
333f0 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
33400 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
33410 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
33420 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
33430 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
33440 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
33450 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
33460 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
33470 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
33480 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a  LITE_TRANSIENT.*
33490 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61  * then SQLite ma
334a0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
334b0 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70  e result into sp
334c0 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ace obtained fro
334d0 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  m.** from [sqlit
334e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66  e3_malloc()] bef
334f0 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a  ore it returns..
33500 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33510 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
33520 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
33530 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
33540 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
33550 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
33560 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20  on to be a copy 
33570 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63  the.** [unprotec
33580 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
33590 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  e] object specif
335a0 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70  ied by the 2nd p
335b0 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a  arameter.  ^The.
335c0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
335d0 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
335e0 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ace makes a copy
335f0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
33600 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68  _value].** so th
33610 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
33620 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64  value] specified
33630 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
33640 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a  r may change or.
33650 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ** be deallocate
33660 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
33670 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72  result_value() r
33680 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68  eturns without h
33690 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74  arm..** ^A [prot
336a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
336b0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20  lue] object may 
336c0 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77  always be used w
336d0 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  here an.** [unpr
336e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
336f0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73  value] object is
33700 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69   required, so ei
33710 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20  ther.** kind of 
33720 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
33730 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73  object can be us
33740 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74  ed with this int
33750 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66  erface..**.** If
33760 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
33770 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
33780 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65  within the diffe
33790 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74  rent thread.** t
337a0 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74  han the one cont
337b0 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69  aining the appli
337c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
337d0 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63  unction that rec
337e0 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71  eived.** the [sq
337f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70  lite3_context] p
33800 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75  ointer, the resu
33810 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
33820 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
33830 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73  e3_result_blob(s
33840 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33850 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
33860 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
33870 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
33880 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73  _result_double(s
33890 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
338a0 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73   double);.void s
338b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
338c0 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ror(sqlite3_cont
338d0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
338e0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
338f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33900 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  or16(sqlite3_con
33910 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
33920 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  d*, int);.void s
33930 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33940 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74  ror_toobig(sqlit
33950 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
33960 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
33970 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71  t_error_nomem(sq
33980 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
33990 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
339a0 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
339b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
339c0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
339d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
339e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
339f0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
33a00 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36  ite3_result_int6
33a10 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  4(sqlite3_contex
33a20 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t*, sqlite3_int6
33a30 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  4);.void sqlite3
33a40 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c  _result_null(sql
33a50 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
33a60 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
33a70 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ult_text(sqlite3
33a80 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
33a90 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69   char*, int, voi
33aa0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
33ab0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
33ac0 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  t_text16(sqlite3
33ad0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
33ae0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
33af0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
33b00 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
33b10 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  t_text16le(sqlit
33b20 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
33b30 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
33b40 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
33b50 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
33b60 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  lt_text16be(sqli
33b70 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
33b80 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
33b90 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
33ba0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
33bb0 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ult_value(sqlite
33bc0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
33bd0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69  te3_value*);.voi
33be0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
33bf0 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
33c00 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
33c10 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
33c20 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20  REF: Define New 
33c30 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e  Collating Sequen
33c40 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ces.**.** ^These
33c50 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20   functions add, 
33c60 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66  remove, or modif
33c70 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20  y a [collation] 
33c80 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
33c90 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
33ca0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
33cb0 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69  cified as the fi
33cc0 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
33cd0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
33ce0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69   the collation i
33cf0 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
33d00 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  .** for sqlite3_
33d10 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33d20 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
33d30 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
33d40 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54  v2().** and a UT
33d50 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
33d60 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
33d70 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
33d80 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
33d90 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e  )..** ^Collation
33da0 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70   names that comp
33db0 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64  are equal accord
33dc0 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ing to [sqlite3_
33dd0 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a  strnicmp()] are.
33de0 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  ** considered to
33df0 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d   be the same nam
33e00 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74  e..**.** ^(The t
33e10 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65  hird argument (e
33e20 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65  TextRep) must be
33e30 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73   one of the cons
33e40 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  tants:.** <ul>.*
33e50 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
33e60 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  TF8],.** <li> [S
33e70 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a  QLITE_UTF16LE],.
33e80 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
33e90 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69  UTF16BE],.** <li
33ea0 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  > [SQLITE_UTF16]
33eb0 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
33ec0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
33ed0 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  ED]..** </ul>)^.
33ee0 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70  ** ^The eTextRep
33ef0 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d   argument determ
33f00 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e  ines the encodin
33f10 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73  g of strings pas
33f20 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f  sed.** to the co
33f30 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
33f40 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c   callback, xCall
33f50 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  back..** ^The [S
33f60 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64  QLITE_UTF16] and
33f70 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
33f80 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66  LIGNED] values f
33f90 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66  or eTextRep.** f
33fa0 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20  orce strings to 
33fb0 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61  be UTF16 with na
33fc0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
33fd0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
33fe0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
33ff0 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52  value for eTextR
34000 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67  ep forces string
34010 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e  s to begin.** on
34020 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64   an even byte ad
34030 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dress..**.** ^Th
34040 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
34050 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61  t, pArg, is an a
34060 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
34070 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
34080 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67  passed.** throug
34090 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  h as the first a
340a0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
340b0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
340c0 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  n callback..**.*
340d0 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
340e0 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b  ument, xCallback
340f0 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  , is a pointer t
34100 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
34110 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75  function..** ^Mu
34120 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67  ltiple collating
34130 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62   functions can b
34140 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  e registered usi
34150 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  ng the same name
34160 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66   but.** with dif
34170 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20  ferent eTextRep 
34180 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53  parameters and S
34190 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77  QLite will use w
341a0 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63  hichever.** func
341b0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68  tion requires th
341c0 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
341d0 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d  f data transform
341e0 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68  ation..** ^If th
341f0 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75  e xCallback argu
34200 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65  ment is NULL the
34210 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  n the collating 
34220 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64  function is.** d
34230 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61  eleted.  ^When a
34240 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ll collating fun
34250 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68  ctions having th
34260 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20  e same name are 
34270 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74  deleted,.** that
34280 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   collation is no
34290 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a   longer usable..
342a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61  **.** ^The colla
342b0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
342c0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
342d0 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66  d with a copy of
342e0 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70   the pArg .** ap
342f0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
34300 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20  ointer and with 
34310 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74  two strings in t
34320 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
34330 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
34340 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e  eTextRep argumen
34350 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e  t.  The collatin
34360 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
34370 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74  return an.** int
34380 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67  eger that is neg
34390 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20  ative, zero, or 
343a0 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74  positive.** if t
343b0 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20  he first string 
343c0 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71  is less than, eq
343d0 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74  ual to, or great
343e0 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f  er than the seco
343f0 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  nd,.** respectiv
34400 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e  ely.  A collatin
34410 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
34420 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68  always return th
34430 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a  e same answer.**
34440 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20   given the same 
34450 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20  inputs.  If two 
34460 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e  or more collatin
34470 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  g functions are 
34480 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f  registered.** to
34490 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74   the same collat
344a0 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20  ion name (using 
344b0 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52  different eTextR
344c0 65 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20  ep values) then 
344d0 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65  all.** must give
344e0 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61   an equivalent a
344f0 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b  nswer when invok
34500 65 64 20 77 69 74 68 20 65 71 75 69 76 61 6c 65  ed with equivale
34510 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  nt strings..** T
34520 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
34530 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20  ction must obey 
34540 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72  the following pr
34550 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c  operties for all
34560 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42  .** strings A, B
34570 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c  , and C:.**.** <
34580 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  ol>.** <li> If A
34590 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a  ==B then B==A..*
345a0 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61  * <li> If A==B a
345b0 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d  nd B==C then A==
345c0 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26  C..** <li> If A&
345d0 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41  lt;B THEN B&gt;A
345e0 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c  ..** <li> If A&l
345f0 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74  t;B and B&lt;C t
34600 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c  hen A&lt;C..** <
34610 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  /ol>.**.** If a 
34620 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
34630 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20  on fails any of 
34640 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72  the above constr
34650 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a  aints and that.*
34660 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  * collating func
34670 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65  tion is  registe
34680 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68  red and used, th
34690 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
346a0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20  of SQLite.** is 
346b0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
346c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72   ^The sqlite3_cr
346d0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
346e0 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  2() works like s
346f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
34700 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74  llation().** wit
34710 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74  h the addition t
34720 68 61 74 20 74 68 65 20 78 44 65 73 74 72 6f 79  hat the xDestroy
34730 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
34740 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65  oked on pArg whe
34750 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69  n.** the collati
34760 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  ng function is d
34770 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c  eleted..** ^Coll
34780 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
34790 61 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e  are deleted when
347a0 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69   they are overri
347b0 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a  dden by later.**
347c0 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f   calls to the co
347d0 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  llation creation
347e0 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68   functions or wh
347f0 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  en the.** [datab
34800 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
34810 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20  is closed using 
34820 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
34830 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44  ]..**.** ^The xD
34840 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20  estroy callback 
34850 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61  is <u>not</u> ca
34860 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20  lled if the .** 
34870 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
34880 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75  ollation_v2() fu
34890 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41  nction fails.  A
348a0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
348b0 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
348c0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
348d0 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20  ion_v2() with a 
348e0 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f  non-NULL xDestro
348f0 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  y argument shoul
34900 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20  d .** check the 
34910 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20  return code and 
34920 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61  dispose of the a
34930 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
34940 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73  pointer.** thems
34950 65 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 61  elves rather tha
34960 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69  n expecting SQLi
34970 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20  te to deal with 
34980 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20  it for them..** 
34990 54 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e  This is differen
349a0 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68  t from every oth
349b0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
349c0 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73  ace.  The incons
349d0 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75  istency .** is u
349e0 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63  nfortunate but c
349f0 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
34a00 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
34a10 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20  g backwards .** 
34a20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
34a30 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20  *.** See also:  
34a40 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
34a50 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64  on_needed()] and
34a60 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
34a70 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e  ion_needed16()].
34a80 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
34a90 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
34aa0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
34ab0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
34ac0 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
34ad0 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
34ae0 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
34af0 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
34b00 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
34b10 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69  onst void*).);.i
34b20 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
34b30 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a  e_collation_v2(.
34b40 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
34b50 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
34b60 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
34b70 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67  p, .  void *pArg
34b80 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
34b90 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
34ba0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
34bb0 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69  st void*),.  voi
34bc0 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
34bd0 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  d*).);.int sqlit
34be0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34bf0 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
34c00 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  *, .  const void
34c10 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65   *zName,.  int e
34c20 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
34c30 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
34c40 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
34c50 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
34c60 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
34c70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34c80 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65  EF: Collation Ne
34c90 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  eded Callbacks.*
34ca0 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68  *.** ^To avoid h
34cb0 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65  aving to registe
34cc0 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20  r all collation 
34cd0 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65  sequences before
34ce0 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63   a database.** c
34cf0 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69  an be used, a si
34d00 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ngle callback fu
34d10 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
34d20 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68  gistered with th
34d30 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
34d40 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65  onnection] to be
34d50 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
34d60 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63  r an undefined c
34d70 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
34d80 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64  ence is required
34d90 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
34da0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69  function is regi
34db0 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
34dc0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
34dd0 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c  on_needed() API,
34de0 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70  .** then it is p
34df0 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20  assed the names 
34e00 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  of undefined col
34e10 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
34e20 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65   as strings.** e
34e30 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e  ncoded in UTF-8.
34e40 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c   ^If sqlite3_col
34e50 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
34e60 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68  ) is used,.** th
34e70 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73  e names are pass
34e80 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
34e90 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62  machine native b
34ea0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41  yte order..** ^A
34eb0 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20   call to either 
34ec0 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65  function replace
34ed0 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63  s the existing c
34ee0 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20  ollation-needed 
34ef0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
34f00 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  ^(When the callb
34f10 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ack is invoked, 
34f20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
34f30 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63  nt passed is a c
34f40 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65  opy.** of the se
34f50 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
34f60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
34f70 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a  on_needed() or.*
34f80 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  * sqlite3_collat
34f90 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20  ion_needed16(). 
34fa0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
34fb0 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61  ment is the data
34fc0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
34fd0 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  on.  The third a
34fe0 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
34ff0 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  f [SQLITE_UTF8],
35000 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
35010 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  ],.** or [SQLITE
35020 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63  _UTF16LE], indic
35030 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64  ating the most d
35040 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66  esirable form of
35050 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a   the collation.*
35060 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74  * sequence funct
35070 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54  ion required.  T
35080 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
35090 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
350a0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72  of the.** requir
350b0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
350c0 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  uence.)^.**.** T
350d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
350e0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69  tion should regi
350f0 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64  ster the desired
35100 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67   collation using
35110 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
35120 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d  ate_collation()]
35130 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
35140 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d  e_collation16()]
35150 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
35160 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
35170 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  n_v2()]..*/.int 
35180 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
35190 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69  n_needed(.  sqli
351a0 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20  te3*, .  void*, 
351b0 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
351c0 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
351d0 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61  extRep,const cha
351e0 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  r*).);.int sqlit
351f0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
35200 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ded16(.  sqlite3
35210 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76  *, .  void*,.  v
35220 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
35230 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
35240 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  ep,const void*).
35250 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54  );..#ifdef SQLIT
35260 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a  E_HAS_CODEC./*.*
35270 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65  * Specify the ke
35280 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74  y for an encrypt
35290 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68  ed database.  Th
352a0 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  is routine shoul
352b0 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72  d be.** called r
352c0 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74  ight after sqlit
352d0 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a  e3_open()..**.**
352e0 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
352f0 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
35300 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
35310 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
35320 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
35330 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
35340 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74  te3_key(.  sqlit
35350 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
35360 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
35370 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
35380 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
35390 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
353a0 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b  Key     /* The k
353b0 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
353c0 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f  Change the key o
353d0 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  n an open databa
353e0 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72  se.  If the curr
353f0 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20  ent database is 
35400 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64  not.** encrypted
35410 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  , this routine w
35420 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20  ill encrypt it. 
35430 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e   If pNew==0 or n
35440 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64  New==0, the.** d
35450 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79  atabase is decry
35460 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  pted..**.** The 
35470 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
35480 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
35490 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
354a0 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
354b0 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
354c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
354d0 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20  ekey(.  sqlite3 
354e0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
354f0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
35500 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
35510 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
35520 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
35530 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20       /* The new 
35540 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
35550 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74   Specify the act
35560 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20  ivation key for 
35570 61 20 53 45 45 20 64 61 74 61 62 61 73 65 2e 20  a SEE database. 
35580 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69   Unless .** acti
35590 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74  vated, none of t
355a0 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20  he SEE routines 
355b0 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f  will work..*/.vo
355c0 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76  id sqlite3_activ
355d0 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74  ate_see(.  const
355e0 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61   char *zPassPhra
355f0 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74  se        /* Act
35600 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a  ivation phrase *
35610 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66  /.);.#endif..#if
35620 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c  def SQLITE_ENABL
35630 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70  E_CEROD./*.** Sp
35640 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61  ecify the activa
35650 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43  tion key for a C
35660 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20  EROD database.  
35670 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76  Unless .** activ
35680 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68  ated, none of th
35690 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73  e CEROD routines
356a0 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76   will work..*/.v
356b0 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69  oid sqlite3_acti
356c0 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f  vate_cerod(.  co
356d0 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50  nst char *zPassP
356e0 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20  hrase        /* 
356f0 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73  Activation phras
35700 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a  e */.);.#endif..
35710 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
35720 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f  Suspend Executio
35730 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69  n For A Short Ti
35740 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  me.**.** The sql
35750 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e  ite3_sleep() fun
35760 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65  ction causes the
35770 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20   current thread 
35780 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75  to suspend execu
35790 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c  tion.** for at l
357a0 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66  east a number of
357b0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70   milliseconds sp
357c0 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70  ecified in its p
357d0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
357e0 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  If the operating
357f0 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74   system does not
35800 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72   support sleep r
35810 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20  equests with.** 
35820 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65  millisecond time
35830 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65   resolution, the
35840 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20  n the time will 
35850 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f  be rounded up to
35860 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20  .** the nearest 
35870 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62  second. The numb
35880 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
35890 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75  ds of sleep actu
358a0 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65  ally.** requeste
358b0 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61  d from the opera
358c0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72  ting system is r
358d0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
358e0 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74  SQLite implement
358f0 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  s this interface
35900 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20   by calling the 
35910 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68  xSleep().** meth
35920 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
35930 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
35940 6f 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20  object.  If the 
35950 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a  xSleep() method.
35960 2a 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  ** of the defaul
35970 74 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70  t VFS is not imp
35980 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74  lemented correct
35990 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65  ly, or not imple
359a0 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c  mented at.** all
359b0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
359c0 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ior of sqlite3_s
359d0 6c 65 65 70 28 29 20 6d 61 79 20 64 65 76 69 61  leep() may devia
359e0 74 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63  te from the desc
359f0 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68  ription.** in th
35a00 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67  e previous parag
35a10 72 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  raphs..*/.int sq
35a20 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29  lite3_sleep(int)
35a30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35a40 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46  F: Name Of The F
35a50 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65  older Holding Te
35a60 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a  mporary Files.**
35a70 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c  .** ^(If this gl
35a80 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73  obal variable is
35a90 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
35aa0 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
35ab0 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20   is.** the name 
35ac0 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b  of a folder (a.k
35ad0 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20  .a. directory), 
35ae0 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61  then all tempora
35af0 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61  ry files.** crea
35b00 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 68  ted by SQLite wh
35b10 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74  en using a built
35b20 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  -in [sqlite3_vfs
35b30 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20   | VFS].** will 
35b40 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61  be placed in tha
35b50 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20  t directory.)^  
35b60 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c  ^If this variabl
35b70 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  e.** is a NULL p
35b80 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
35b90 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73  ite performs a s
35ba0 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70  earch for an app
35bb0 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70  ropriate.** temp
35bc0 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63  orary file direc
35bd0 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69  tory..**.** It i
35be0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65  s not safe to re
35bf0 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ad or modify thi
35c00 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f  s variable in mo
35c10 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74  re than one.** t
35c20 68 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e  hread at a time.
35c30 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65    It is not safe
35c40 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69   to read or modi
35c50 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
35c60 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61  .** if a [databa
35c70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
35c80 73 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20  s being used at 
35c90 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e  the same time in
35ca0 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74   a separate.** t
35cb0 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20  hread..** It is 
35cc0 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68  intended that th
35cd0 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73  is variable be s
35ce0 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61  et once.** as pa
35cf0 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e  rt of process in
35d00 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
35d10 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69   before any SQLi
35d20 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  te interface.** 
35d30 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65  routines have be
35d40 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68  en called and th
35d50 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
35d60 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65   remain unchange
35d70 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e  d.** thereafter.
35d80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d  .**.** ^The [tem
35d90 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
35da0 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f  y pragma] may mo
35db0 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
35dc0 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20  le and cause.** 
35dd0 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  it to point to m
35de0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
35df0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
35e00 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d  loc].  ^Furtherm
35e10 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d  ore,.** the [tem
35e20 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
35e30 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73  y pragma] always
35e40 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e   assumes that an
35e50 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74  y string.** that
35e60 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70   this variable p
35e70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64  oints to is held
35e80 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   in memory obtai
35e90 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71  ned from .** [sq
35ea0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e  lite3_malloc] an
35eb0 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79  d the pragma may
35ec0 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65   attempt to free
35ed0 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20   that memory.** 
35ee0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
35ef0 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20  ree]..** Hence, 
35f00 69 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  if this variable
35f10 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72   is modified dir
35f20 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74  ectly, either it
35f30 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61   should be.** ma
35f40 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20  de NULL or made 
35f50 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f  to point to memo
35f60 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
35f70 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
35f80 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65  ].** or else the
35f90 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d   use of the [tem
35fa0 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
35fb0 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64  y pragma] should
35fc0 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 0a   be avoided..**.
35fd0 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
35fe0 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73  ndows Runtime us
35ff0 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65  ers:</b>  The te
36000 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72  mporary director
36010 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a  y must be set.**
36020 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
36030 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5d  g [sqlite3_open]
36040 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
36050 6e 5f 76 32 5d 2e 20 20 4f 74 68 65 72 77 69 73  n_v2].  Otherwis
36060 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65  e, various.** fe
36070 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75  atures that requ
36080 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  ire the use of t
36090 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d  emporary files m
360a0 61 79 20 66 61 69 6c 2e 20 20 48 65 72 65 20 69  ay fail.  Here i
360b0 73 20 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65 20  s an.** example 
360c0 6f 66 20 68 6f 77 20 74 6f 20 64 6f 20 74 68 69  of how to do thi
360d0 73 20 75 73 69 6e 67 20 43 2b 2b 20 77 69 74 68  s using C++ with
360e0 20 74 68 65 20 57 69 6e 64 6f 77 73 20 52 75 6e   the Windows Run
360f0 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  time:.**.** <blo
36100 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
36110 20 4c 50 43 57 53 54 52 20 7a 50 61 74 68 20 3d   LPCWSTR zPath =
36120 20 57 69 6e 64 6f 77 73 3a 3a 53 74 6f 72 61 67   Windows::Storag
36130 65 3a 3a 41 70 70 6c 69 63 61 74 69 6f 6e 44 61  e::ApplicationDa
36140 74 61 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a 2a  ta::Current->.**
36150 20 26 6e 62 73 70 3b 20 20 20 20 20 54 65 6d 70   &nbsp;     Temp
36160 6f 72 61 72 79 46 6f 6c 64 65 72 2d 3e 50 61 74  oraryFolder->Pat
36170 68 2d 3e 44 61 74 61 28 29 3b 0a 2a 2a 20 63 68  h->Data();.** ch
36180 61 72 20 7a 50 61 74 68 42 75 66 26 23 39 31 3b  ar zPathBuf&#91;
36190 4d 41 58 5f 50 41 54 48 20 2b 20 31 26 23 39 33  MAX_PATH + 1&#93
361a0 3b 3b 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a 50 61  ;;.** memset(zPa
361b0 74 68 42 75 66 2c 20 30 2c 20 73 69 7a 65 6f 66  thBuf, 0, sizeof
361c0 28 7a 50 61 74 68 42 75 66 29 29 3b 0a 2a 2a 20  (zPathBuf));.** 
361d0 57 69 64 65 43 68 61 72 54 6f 4d 75 6c 74 69 42  WideCharToMultiB
361e0 79 74 65 28 43 50 5f 55 54 46 38 2c 20 30 2c 20  yte(CP_UTF8, 0, 
361f0 7a 50 61 74 68 2c 20 2d 31 2c 20 7a 50 61 74 68  zPath, -1, zPath
36200 42 75 66 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74  Buf, sizeof(zPat
36210 68 42 75 66 29 2c 0a 2a 2a 20 26 6e 62 73 70 3b  hBuf),.** &nbsp;
36220 20 20 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c 4c 29       NULL, NULL)
36230 3b 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 65 6d  ;.** sqlite3_tem
36240 70 5f 64 69 72 65 63 74 6f 72 79 20 3d 20 73 71  p_directory = sq
36250 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 25  lite3_mprintf("%
36260 73 22 2c 20 7a 50 61 74 68 42 75 66 29 3b 0a 2a  s", zPathBuf);.*
36270 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
36280 75 6f 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  uote>.*/.SQLITE_
36290 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c  EXTERN char *sql
362a0 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
362b0 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ory;../*.** CAPI
362c0 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68  3REF: Name Of Th
362d0 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67  e Folder Holding
362e0 20 44 61 74 61 62 61 73 65 20 46 69 6c 65 73 0a   Database Files.
362f0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20  **.** ^(If this 
36300 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20  global variable 
36310 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
36320 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69   to a string whi
36330 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  ch is.** the nam
36340 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61  e of a folder (a
36350 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29  .k.a. directory)
36360 2c 20 74 68 65 6e 20 61 6c 6c 20 64 61 74 61 62  , then all datab
36370 61 73 65 20 66 69 6c 65 73 0a 2a 2a 20 73 70 65  ase files.** spe
36380 63 69 66 69 65 64 20 77 69 74 68 20 61 20 72 65  cified with a re
36390 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65 20  lative pathname 
363a0 61 6e 64 20 63 72 65 61 74 65 64 20 6f 72 20 61  and created or a
363b0 63 63 65 73 73 65 64 20 62 79 0a 2a 2a 20 53 51  ccessed by.** SQ
363c0 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20  Lite when using 
363d0 61 20 62 75 69 6c 74 2d 69 6e 20 77 69 6e 64 6f  a built-in windo
363e0 77 73 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  ws [sqlite3_vfs 
363f0 7c 20 56 46 53 5d 20 77 69 6c 6c 20 62 65 20 61  | VFS] will be a
36400 73 73 75 6d 65 64 0a 2a 2a 20 74 6f 20 62 65 20  ssumed.** to be 
36410 72 65 6c 61 74 69 76 65 20 74 6f 20 74 68 61 74  relative to that
36420 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 5e 49   directory.)^ ^I
36430 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
36440 69 73 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  is a NULL.** poi
36450 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
36460 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61  e assumes that a
36470 6c 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ll database file
36480 73 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 77  s specified.** w
36490 69 74 68 20 61 20 72 65 6c 61 74 69 76 65 20 70  ith a relative p
364a0 61 74 68 6e 61 6d 65 20 61 72 65 20 72 65 6c 61  athname are rela
364b0 74 69 76 65 20 74 6f 20 74 68 65 20 63 75 72 72  tive to the curr
364c0 65 6e 74 20 64 69 72 65 63 74 6f 72 79 0a 2a 2a  ent directory.**
364d0 20 66 6f 72 20 74 68 65 20 70 72 6f 63 65 73 73   for the process
364e0 2e 20 20 4f 6e 6c 79 20 74 68 65 20 77 69 6e 64  .  Only the wind
364f0 6f 77 73 20 56 46 53 20 6d 61 6b 65 73 20 75 73  ows VFS makes us
36500 65 20 6f 66 20 74 68 69 73 20 67 6c 6f 62 61 6c  e of this global
36510 0a 2a 2a 20 76 61 72 69 61 62 6c 65 3b 20 69 74  .** variable; it
36520 20 69 73 20 69 67 6e 6f 72 65 64 20 62 79 20 74   is ignored by t
36530 68 65 20 75 6e 69 78 20 56 46 53 2e 0a 2a 2a 0a  he unix VFS..**.
36540 2a 2a 20 43 68 61 6e 67 69 6e 67 20 74 68 65 20  ** Changing the 
36550 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 76 61  value of this va
36560 72 69 61 62 6c 65 20 77 68 69 6c 65 20 61 20 64  riable while a d
36570 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36580 6f 6e 20 69 73 0a 2a 2a 20 6f 70 65 6e 20 63 61  on is.** open ca
36590 6e 20 72 65 73 75 6c 74 20 69 6e 20 61 20 63 6f  n result in a co
365a0 72 72 75 70 74 20 64 61 74 61 62 61 73 65 2e 0a  rrupt database..
365b0 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  **.** It is not 
365c0 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
365d0 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
365e0 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61  able in more tha
365f0 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20  n one.** thread 
36600 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69  at a time.  It i
36610 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65  s not safe to re
36620 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ad or modify thi
36630 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66  s variable.** if
36640 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
36650 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
36660 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61  g used at the sa
36670 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70  me time in a sep
36680 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e  arate.** thread.
36690 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64  .** It is intend
366a0 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ed that this var
366b0 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63  iable be set onc
366c0 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  e.** as part of 
366d0 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
366e0 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72  zation and befor
366f0 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
36700 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e  erface.** routin
36710 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  es have been cal
36720 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69  led and that thi
36730 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69  s variable remai
36740 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74  n unchanged.** t
36750 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a  hereafter..**.**
36760 20 5e 54 68 65 20 5b 64 61 74 61 5f 73 74 6f 72   ^The [data_stor
36770 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
36780 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74  ma] may modify t
36790 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64  his variable and
367a0 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20   cause.** it to 
367b0 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
367c0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
367d0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20  qlite3_malloc]. 
367e0 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a   ^Furthermore,.*
367f0 2a 20 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72  * the [data_stor
36800 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
36810 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d  ma] always assum
36820 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69  es that any stri
36830 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20  ng.** that this 
36840 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20  variable points 
36850 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65  to is held in me
36860 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
36870 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
36880 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20  malloc] and the 
36890 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d  pragma may attem
368a0 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20  pt to free that 
368b0 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20  memory.** using 
368c0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a  [sqlite3_free]..
368d0 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69  ** Hence, if thi
368e0 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f  s variable is mo
368f0 64 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c  dified directly,
36900 20 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c   either it shoul
36910 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c  d be.** made NUL
36920 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69  L or made to poi
36930 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74  nt to memory obt
36940 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
36950 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f  te3_malloc].** o
36960 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f  r else the use o
36970 66 20 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72  f the [data_stor
36980 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
36990 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76  ma] should be av
369a0 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  oided..*/.SQLITE
369b0 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71  _EXTERN char *sq
369c0 6c 69 74 65 33 5f 64 61 74 61 5f 64 69 72 65 63  lite3_data_direc
369d0 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tory;../*.** CAP
369e0 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20  I3REF: Test For 
369f0 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65  Auto-Commit Mode
36a00 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
36a10 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a  utocommit mode}.
36a20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36a30 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
36a40 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  t() interface re
36a50 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f  turns non-zero o
36a60 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65  r.** zero if the
36a70 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20   given database 
36a80 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72  connection is or
36a90 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63   is not in autoc
36aa0 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72  ommit mode,.** r
36ab0 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41  espectively.  ^A
36ac0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
36ad0 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  s on by default.
36ae0 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20  .** ^Autocommit 
36af0 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64  mode is disabled
36b00 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74   by a [BEGIN] st
36b10 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74  atement..** ^Aut
36b20 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
36b30 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20  re-enabled by a 
36b40 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c  [COMMIT] or [ROL
36b50 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  LBACK]..**.** If
36b60 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f   certain kinds o
36b70 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f  f errors occur o
36b80 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69  n a statement wi
36b90 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61  thin a multi-sta
36ba0 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61  tement.** transa
36bb0 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e  ction (errors in
36bc0 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f  cluding [SQLITE_
36bd0 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49  FULL], [SQLITE_I
36be0 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  OERR],.** [SQLIT
36bf0 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54  E_NOMEM], [SQLIT
36c00 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51  E_BUSY], and [SQ
36c10 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29  LITE_INTERRUPT])
36c20 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61   then the.** tra
36c30 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62  nsaction might b
36c40 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
36c50 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68  tomatically.  Th
36c60 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a  e only way to.**
36c70 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65   find out whethe
36c80 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74  r SQLite automat
36c90 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
36ca0 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
36cb0 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65  on after.** an e
36cc0 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74  rror is to use t
36cd0 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  his function..**
36ce0 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74  .** If another t
36cf0 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68  hread changes th
36d00 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61  e autocommit sta
36d10 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62  tus of the datab
36d20 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
36d30 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75  n while this rou
36d40 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c  tine is running,
36d50 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
36d60 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64   value.** is und
36d70 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  efined..*/.int s
36d80 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
36d90 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b  ommit(sqlite3*);
36da0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36db0 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62  : Find The Datab
36dc0 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20  ase Handle Of A 
36dd0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
36de0 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  nt.**.** ^The sq
36df0 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
36e00 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
36e10 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
36e20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
36e30 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61  le.** to which a
36e40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
36e50 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20  ment] belongs.  
36e60 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63  ^The [database c
36e70 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65  onnection].** re
36e80 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
36e90 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74  3_db_handle is t
36ea0 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
36eb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
36ec0 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66 69   that was the fi
36ed0 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rst argument.** 
36ee0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
36ef0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61  prepare_v2()] ca
36f00 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69 61  ll (or its varia
36f10 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75 73  nts) that was us
36f20 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20  ed to.** create 
36f30 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  the statement in
36f40 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65   the first place
36f50 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
36f60 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28  lite3_db_handle(
36f70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
36f80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36f90 20 52 65 74 75 72 6e 20 54 68 65 20 46 69 6c 65   Return The File
36fa0 6e 61 6d 65 20 46 6f 72 20 41 20 44 61 74 61 62  name For A Datab
36fb0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
36fc0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36fd0 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 44 2c  3_db_filename(D,
36fe0 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  N) interface ret
36ff0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
37000 6f 20 61 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  o a filename.** 
37010 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
37020 64 61 74 61 62 61 73 65 20 4e 20 6f 66 20 63 6f  database N of co
37030 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 5e 54 68  nnection D.  ^Th
37040 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
37050 66 69 6c 65 0a 2a 2a 20 68 61 73 20 74 68 65 20  file.** has the 
37060 6e 61 6d 65 20 22 6d 61 69 6e 22 2e 20 20 49 66  name "main".  If
37070 20 74 68 65 72 65 20 69 73 20 6e 6f 20 61 74 74   there is no att
37080 61 63 68 65 64 20 64 61 74 61 62 61 73 65 20 4e  ached database N
37090 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
370a0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  .** connection D
370b0 2c 20 6f 72 20 69 66 20 64 61 74 61 62 61 73 65  , or if database
370c0 20 4e 20 69 73 20 61 20 74 65 6d 70 6f 72 61 72   N is a temporar
370d0 79 20 6f 72 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  y or in-memory d
370e0 61 74 61 62 61 73 65 2c 20 74 68 65 6e 0a 2a 2a  atabase, then.**
370f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
37100 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
37110 2a 2a 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  ** ^The filename
37120 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
37130 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  s function is th
37140 65 20 6f 75 74 70 75 74 20 6f 66 20 74 68 65 0a  e output of the.
37150 2a 2a 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  ** xFullPathname
37160 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
37170 56 46 53 5d 2e 20 20 5e 49 6e 20 6f 74 68 65 72  VFS].  ^In other
37180 20 77 6f 72 64 73 2c 20 74 68 65 20 66 69 6c 65   words, the file
37190 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  name.** will be 
371a0 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
371b0 6e 61 6d 65 2c 20 65 76 65 6e 20 69 66 20 74 68  name, even if th
371c0 65 20 66 69 6c 65 6e 61 6d 65 20 75 73 65 64 0a  e filename used.
371d0 2a 2a 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  ** to open the d
371e0 61 74 61 62 61 73 65 20 6f 72 69 67 69 6e 61 6c  atabase original
371f0 6c 79 20 77 61 73 20 61 20 55 52 49 20 6f 72 20  ly was a URI or 
37200 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d  relative pathnam
37210 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  e..*/.const char
37220 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c   *sqlite3_db_fil
37230 65 6e 61 6d 65 28 73 71 6c 69 74 65 33 20 2a 64  ename(sqlite3 *d
37240 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  b, const char *z
37250 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  DbName);../*.** 
37260 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
37270 69 6e 65 20 69 66 20 61 20 64 61 74 61 62 61 73  ine if a databas
37280 65 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79 0a 2a  e is read-only.*
37290 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
372a0 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28 44 2c  3_db_readonly(D,
372b0 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  N) interface ret
372c0 75 72 6e 73 20 31 20 69 66 20 74 68 65 20 64 61  urns 1 if the da
372d0 74 61 62 61 73 65 20 4e 0a 2a 2a 20 6f 66 20 63  tabase N.** of c
372e0 6f 6e 6e 65 63 74 69 6f 6e 20 44 20 69 73 20 72  onnection D is r
372f0 65 61 64 2d 6f 6e 6c 79 2c 20 30 20 69 66 20 69  ead-only, 0 if i
37300 74 20 69 73 20 72 65 61 64 2f 77 72 69 74 65 2c  t is read/write,
37310 20 6f 72 20 2d 31 20 69 66 20 4e 20 69 73 20 6e   or -1 if N is n
37320 6f 74 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  ot.** the name o
37330 66 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20  f a database on 
37340 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2f  connection D..*/
37350 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f  .int sqlite3_db_
37360 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33  readonly(sqlite3
37370 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 61 72   *db, const char
37380 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a   *zDbName);../*.
37390 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e  ** CAPI3REF: Fin
373a0 64 20 74 68 65 20 6e 65 78 74 20 70 72 65 70 61  d the next prepa
373b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
373c0 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
373d0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
373e0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78  inter to the nex
373f0 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  t [prepared stat
37400 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20  ement] after.** 
37410 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64  pStmt associated
37420 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
37430 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37440 70 44 62 2e 20 20 5e 49 66 20 70 53 74 6d 74 20  pDb.  ^If pStmt 
37450 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20  is NULL.** then 
37460 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72  this interface r
37470 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
37480 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 70 72   to the first pr
37490 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
374a0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
374b0 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65  ith the database
374c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e   connection pDb.
374d0 20 20 5e 49 66 20 6e 6f 20 70 72 65 70 61 72 65    ^If no prepare
374e0 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73  d statement.** s
374f0 61 74 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e  atisfies the con
37500 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20  ditions of this 
37510 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75  routine, it retu
37520 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20  rns NULL..**.** 
37530 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  The [database co
37540 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65  nnection] pointe
37550 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f  r D in a call to
37560 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  .** [sqlite3_nex
37570 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73  t_stmt(D,S)] mus
37580 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70  t refer to an op
37590 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  en database.** c
375a0 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e  onnection and in
375b0 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74   particular must
375c0 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70   not be a NULL p
375d0 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74  ointer..*/.sqlit
375e0 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33  e3_stmt *sqlite3
375f0 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74  _next_stmt(sqlit
37600 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33  e3 *pDb, sqlite3
37610 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
37620 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37630 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62  Commit And Rollb
37640 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e  ack Notification
37650 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
37660 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
37670 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  mmit_hook() inte
37680 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
37690 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  a callback.** fu
376a0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
376b0 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
376c0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b  transaction is [
376d0 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74  COMMIT | committ
376e0 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c  ed]..** ^Any cal
376f0 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
37700 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
37710 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
37720 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65  ook().** for the
37730 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
37740 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65  onnection is ove
37750 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65  rridden..** ^The
37760 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63   sqlite3_rollbac
37770 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  k_hook() interfa
37780 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
37790 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
377a0 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ion to be invoke
377b0 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61  d whenever a tra
377c0 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c  nsaction is [ROL
377d0 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62  LBACK | rolled b
377e0 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61  ack]..** ^Any ca
377f0 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
37800 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
37810 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63   sqlite3_rollbac
37820 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20  k_hook().** for 
37830 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
37840 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
37850 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e  overridden..** ^
37860 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  The pArg argumen
37870 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  t is passed thro
37880 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ugh to the callb
37890 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ack..** ^If the 
378a0 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f  callback on a co
378b0 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69  mmit hook functi
378c0 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  on returns non-z
378d0 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ero,.** then the
378e0 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65   commit is conve
378f0 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c  rted into a roll
37900 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  back..**.** ^The
37910 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
37920 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20  hook(D,C,P) and 
37930 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
37940 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e  _hook(D,C,P) fun
37950 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e  ctions.** return
37960 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20   the P argument 
37970 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75  from the previou
37980 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 20 73 61  s call of the sa
37990 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f  me function.** o
379a0 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
379b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
379c0 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a   D, or NULL for.
379d0 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  ** the first cal
379e0 6c 20 66 6f 72 20 65 61 63 68 20 66 75 6e 63 74  l for each funct
379f0 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20  ion on D..**.** 
37a00 54 68 65 20 63 6f 6d 6d 69 74 20 61 6e 64 20 72  The commit and r
37a10 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 61 6c  ollback hook cal
37a20 6c 62 61 63 6b 73 20 61 72 65 20 6e 6f 74 20 72  lbacks are not r
37a30 65 65 6e 74 72 61 6e 74 2e 0a 2a 2a 20 54 68 65  eentrant..** The
37a40 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d   callback implem
37a50 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  entation must no
37a60 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
37a70 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
37a80 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
37a90 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
37aa0 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62  nvoked the callb
37ab0 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e  ack.  Any action
37ac0 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74  s.** to modify t
37ad0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
37ae0 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64  ection must be d
37af0 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66  eferred until af
37b00 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  ter the.** compl
37b10 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71  etion of the [sq
37b20 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
37b30 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
37b40 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20  d the commit.** 
37b50 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b  or rollback hook
37b60 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c   in the first pl
37b70 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ace..** Note tha
37b80 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 6f 74  t running any ot
37b90 68 65 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  her SQL statemen
37ba0 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 53 45  ts, including SE
37bb0 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73 2c  LECT statements,
37bc0 0a 2a 2a 20 6f 72 20 6d 65 72 65 6c 79 20 63 61  .** or merely ca
37bd0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  lling [sqlite3_p
37be0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
37bf0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
37c00 5d 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  ] will modify.**
37c10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
37c20 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
37c30 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
37c40 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
37c50 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
37c60 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55  Registering a NU
37c70 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61  LL function disa
37c80 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  bles the callbac
37c90 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74  k..**.** ^When t
37ca0 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63  he commit hook c
37cb0 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
37cc0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68  returns zero, th
37cd0 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70  e [COMMIT].** op
37ce0 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77  eration is allow
37cf0 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e  ed to continue n
37d00 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68  ormally.  ^If th
37d10 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a  e commit hook.**
37d20 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
37d30 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d  o, then the [COM
37d40 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65  MIT] is converte
37d50 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41  d into a [ROLLBA
37d60 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c  CK]..** ^The rol
37d70 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e  lback hook is in
37d80 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62  voked on a rollb
37d90 61 63 6b 20 74 68 61 74 20 72 65 73 75 6c 74 73  ack that results
37da0 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a   from a commit.*
37db0 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67  * hook returning
37dc0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20   non-zero, just 
37dd0 61 73 20 69 74 20 77 6f 75 6c 64 20 62 65 20 77  as it would be w
37de0 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20 72 6f  ith any other ro
37df0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46  llback..**.** ^F
37e00 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
37e10 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 20 74  of this API, a t
37e20 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61  ransaction is sa
37e30 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a  id to have been.
37e40 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69  ** rolled back i
37e50 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52  f an explicit "R
37e60 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65  OLLBACK" stateme
37e70 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2c 20  nt is executed, 
37e80 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f  or.** an error o
37e90 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75  r constraint cau
37ea0 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20  ses an implicit 
37eb0 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75  rollback to occu
37ec0 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62  r..** ^The rollb
37ed0 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ack callback is 
37ee0 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61  not invoked if a
37ef0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a   transaction is.
37f00 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
37f10 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63   rolled back bec
37f20 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73  ause the databas
37f30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
37f40 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65  closed..**.** Se
37f50 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
37f60 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
37f70 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f  )] interface..*/
37f80 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63  .void *sqlite3_c
37f90 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74  ommit_hook(sqlit
37fa0 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  e3*, int(*)(void
37fb0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64  *), void*);.void
37fc0 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61   *sqlite3_rollba
37fd0 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a  ck_hook(sqlite3*
37fe0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a  , void(*)(void *
37ff0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
38000 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
38010 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61   Change Notifica
38020 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
38030 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
38040 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20  3_update_hook() 
38050 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
38060 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
38070 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20  unction.** with 
38080 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
38090 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69  nnection] identi
380a0 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73  fied by the firs
380b0 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  t argument.** to
380c0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
380d0 65 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70  ever a row is up
380e0 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
380f0 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e  or deleted..** ^
38100 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
38110 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
38120 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63  all to this func
38130 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20  tion.** for the 
38140 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
38150 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
38160 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ridden..**.** ^T
38170 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
38180 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
38190 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  to the function 
381a0 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61  to invoke when a
381b0 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74  .** row is updat
381c0 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20  ed, inserted or 
381d0 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  deleted..** ^The
381e0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
381f0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
38200 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
38210 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a   third argument.
38220 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70  ** to sqlite3_up
38230 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20  date_hook()..** 
38240 5e 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ^The second call
38250 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73  back argument is
38260 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
38270 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45  INSERT], [SQLITE
38280 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20  _DELETE],.** or 
38290 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c  [SQLITE_UPDATE],
382a0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
382b0 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  e operation that
382c0 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c   caused the call
382d0 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  back.** to be in
382e0 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 74  voked..** ^The t
382f0 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
38300 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
38310 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
38320 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  n pointers to th
38330 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e  e.** database an
38340 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e  d table name con
38350 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65  taining the affe
38360 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e 54 68  cted row..** ^Th
38370 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b  e final callback
38380 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
38390 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
383a0 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65   row..** ^In the
383b0 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61   case of an upda
383c0 74 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 20  te, this is the 
383d0 5b 72 6f 77 69 64 5d 20 61 66 74 65 72 20 74 68  [rowid] after th
383e0 65 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70  e update takes p
383f0 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  lace..**.** ^(Th
38400 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73  e update hook is
38410 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65   not invoked whe
38420 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65  n internal syste
38430 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20  m tables are.** 
38440 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73  modified (i.e. s
38450 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64  qlite_master and
38460 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65   sqlite_sequence
38470 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ).)^.**.** ^In t
38480 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
38490 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 75  mentation, the u
384a0 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73  pdate hook.** is
384b0 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65   not invoked whe
384c0 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f  n duplication ro
384d0 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 62  ws are deleted b
384e0 65 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20  ecause of an.** 
384f0 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f  [ON CONFLICT | O
38500 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41  N CONFLICT REPLA
38510 43 45 5d 20 63 6c 61 75 73 65 2e 20 20 5e 4e 6f  CE] clause.  ^No
38520 72 20 69 73 20 74 68 65 20 75 70 64 61 74 65 20  r is the update 
38530 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20  hook.** invoked 
38540 77 68 65 6e 20 72 6f 77 73 20 61 72 65 20 64 65  when rows are de
38550 6c 65 74 65 64 20 75 73 69 6e 67 20 74 68 65 20  leted using the 
38560 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69  [truncate optimi
38570 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20  zation]..** The 
38580 65 78 63 65 70 74 69 6f 6e 73 20 64 65 66 69 6e  exceptions defin
38590 65 64 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  ed in this parag
385a0 72 61 70 68 20 6d 69 67 68 74 20 63 68 61 6e 67  raph might chang
385b0 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a  e in a future.**
385c0 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
385d0 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70  te..**.** The up
385e0 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d  date hook implem
385f0 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  entation must no
38600 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
38610 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
38620 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
38630 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
38640 6e 76 6f 6b 65 64 20 74 68 65 20 75 70 64 61 74  nvoked the updat
38650 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74  e hook.  Any act
38660 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66  ions.** to modif
38670 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  y the database c
38680 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62  onnection must b
38690 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c  e deferred until
386a0 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f   after the.** co
386b0 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20  mpletion of the 
386c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
386d0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
386e0 65 72 65 64 20 74 68 65 20 75 70 64 61 74 65 20  ered the update 
386f0 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  hook..** Note th
38700 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
38710 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
38720 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
38730 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
38740 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
38750 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
38760 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
38770 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
38780 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54  agraph..**.** ^T
38790 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74  he sqlite3_updat
387a0 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75  e_hook(D,C,P) fu
387b0 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e  nction.** return
387c0 73 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74  s the P argument
387d0 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f   from the previo
387e0 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 74 68  us call.** on th
387f0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
38800 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20   connection] D, 
38810 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74  or NULL for.** t
38820 68 65 20 66 69 72 73 74 20 63 61