/ Hex Artifact Content
Login

Artifact 922d2907cc2b0177b2c4a3b462f04937750d6edd:


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 69 73  3_close()].** is
23f0: 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e   its destructor.
2400: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
2410: 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   other interface
2420: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73  s (such as.** [s
2430: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2440: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  2()], [sqlite3_c
2450: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2460: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2470: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
2480: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74  )] to name but t
2490: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d  hree) that are m
24a0: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20  ethods on an.** 
24b0: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a  sqlite3 object..
24c0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
24d0: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65  t sqlite3 sqlite
24e0: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  3;../*.** CAPI3R
24f0: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67  EF: 64-Bit Integ
2500: 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57  er Types.** KEYW
2510: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74  ORDS: sqlite_int
2520: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2530: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
2540: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73  here is no cross
2550: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f  -platform way to
2560: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20   specify 64-bit 
2570: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a  integer types.**
2580: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73   SQLite includes
2590: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34   typedefs for 64
25a0: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20  -bit signed and 
25b0: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
25c0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
25d0: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
25e0: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72  qlite3_uint64 ar
25f0: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2600: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  type definitions
2610: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f  ..** The sqlite_
2620: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2630: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72  _uint64 types ar
2640: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20  e supported for 
2650: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d  backwards.** com
2660: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
2670: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2680: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
2690: 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73  lite_int64 types
26a0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
26b0: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  er values.** bet
26c0: 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36  ween -9223372036
26d0: 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39  854775808 and +9
26e0: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
26f0: 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e  07 inclusive.  ^
2700: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  The.** sqlite3_u
2710: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2720: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  _uint64 types ca
2730: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
2740: 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65  values .** betwe
2750: 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37  en 0 and +184467
2760: 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69  44073709551615 i
2770: 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66  nclusive..*/.#if
2780: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
2790: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
27a0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
27b0: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
27c0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
27d0: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
27e0: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
27f0: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
2800: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
2810: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
2820: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
2830: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
2840: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2850: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
2860: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
2870: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
2880: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
2890: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
28a0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
28b0: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
28c0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
28d0: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
28e0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
28f0: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
2900: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
2910: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
2920: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
2930: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
2940: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
2950: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
2960: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
2970: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
2980: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
2990: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
29a0: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
29b0: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
29c0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
29d0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
29e0: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
29f0: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
2a00: 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
2a10: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2a20: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20   routine is the 
2a30: 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
2a40: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
2a50: 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ect..** ^Calls t
2a60: 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  o sqlite3_close(
2a70: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
2a80: 4f 4b 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  OK if the [sqlit
2a90: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  e3] object is.**
2aa0: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65   successfully de
2ab0: 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20  stroyed and all 
2ac0: 61 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f 75  associated resou
2ad0: 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63  rces are dealloc
2ae0: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ated..**.** Appl
2af0: 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b 73  ications must [s
2b00: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
2b10: 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20  | finalize] all 
2b20: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b30: 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  ents].** and [sq
2b40: 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
2b50: 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42   | close] all [B
2b60: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 73  LOB handles] ass
2b70: 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20  ociated with.** 
2b80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2b90: 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74  ject prior to at
2ba0: 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73  tempting to clos
2bb0: 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e  e the object.  ^
2bc0: 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c  If.** sqlite3_cl
2bd0: 6f 73 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ose() is called 
2be0: 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  on a [database c
2bf0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20  onnection] that 
2c00: 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74  still has.** out
2c10: 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72  standing [prepar
2c20: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 6f  ed statements] o
2c30: 72 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  r [BLOB handles]
2c40: 2c 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e  , then it return
2c50: 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59  s.** SQLITE_BUSY
2c60: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71 6c  ..**.** ^If [sql
2c70: 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73  ite3_close()] is
2c80: 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61   invoked while a
2c90: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
2ca0: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61  open,.** the tra
2cb0: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f  nsaction is auto
2cc0: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
2cd0: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   back..**.** The
2ce0: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   C parameter to 
2cf0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
2d00: 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  )] must be eithe
2d10: 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
2d20: 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74  ter or an [sqlit
2d30: 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74  e3] object point
2d40: 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  er obtained.** f
2d50: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  rom [sqlite3_ope
2d60: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
2d70: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  pen16()], or.** 
2d80: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
2d90: 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65  ()], and not pre
2da0: 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a  viously closed..
2db0: 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
2dc0: 74 65 33 5f 63 6c 6f 73 65 28 29 20 77 69 74 68  te3_close() with
2dd0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2de0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 0a 2a  argument is a .*
2df0: 2a 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  * harmless no-op
2e00: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2e10: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a  _close(sqlite3 *
2e20: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
2e30: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
2e40: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
2e50: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
2e60: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
2e70: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
2e80: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
2e90: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
2ea0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
2eb0: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
2ec0: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
2ed0: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
2ee0: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
2ef0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f00: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
2f10: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
2f20: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65  erface.**.** The
2f30: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
2f40: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
2f50: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
2f60: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
2f70: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2f80: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
2f90: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
2fa0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
2fb0: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
2fc0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
2fd0: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
2fe0: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
2ff0: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
3000: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
3010: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
3020: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
3030: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
3040: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
3050: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
3060: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
3070: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
3080: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
3090: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
30a0: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
30b0: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
30c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30d0: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
30e0: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
30f0: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
3100: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3110: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
3120: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
3130: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3140: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
3150: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
3160: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
3170: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
3180: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
3190: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
31a0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
31b0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
31c0: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74  c() is relayed t
31d0: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73  hrough to the 1s
31e0: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61  t argument of ea
31f0: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ch.** callback i
3200: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20  nvocation.  ^If 
3210: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69  the callback poi
3220: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
3230: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c  exec().** is NUL
3240: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62  L, then no callb
3250: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f  ack is ever invo
3260: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72  ked and result r
3270: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72  ows are.** ignor
3280: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3290: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
32a0: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74  ile evaluating t
32b0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
32c0: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  s passed into.**
32d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
32e0: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20   then execution 
32f0: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  of the current s
3300: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61  tatement stops a
3310: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  nd.** subsequent
3320: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
3330: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68  skipped.  ^If th
3340: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3350: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3360: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ).** is not NULL
3370: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20   then any error 
3380: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74  message is writt
3390: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
33a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
33b0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
33c0: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61  )] and passed ba
33d0: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ck through the 5
33e0: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  th parameter..**
33f0: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79   To avoid memory
3400: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c   leaks, the appl
3410: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69  ication should i
3420: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
3430: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72  ree()].** on err
3440: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
3450: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  gs returned thro
3460: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3470: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73  meter of.** of s
3480: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3490: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
34a0: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
34b0: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
34c0: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
34d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
34e0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
34f0: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3500: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3510: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3520: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3530: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3540: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3550: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3560: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3570: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3580: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3590: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
35a0: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
35b0: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
35c0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
35d0: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
35e0: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
35f0: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3600: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3610: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3620: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3630: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3640: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3650: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3660: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3670: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3680: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3690: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
36a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
36b0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
36c0: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
36d0: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
36e0: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
36f0: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3700: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3710: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3720: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3730: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3740: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3750: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3760: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3770: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3780: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3790: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
37a0: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
37b0: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
37c0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
37d0: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
37e0: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
37f0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3800: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3810: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3820: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3830: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3840: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3850: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
3860: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3870: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
3880: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
3890: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
38a0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
38b0: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
38c0: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
38d0: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
38e0: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
38f0: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
3900: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
3910: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
3920: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
3930: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
3940: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
3950: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
3960: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
3970: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
3980: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
3990: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
39a0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
39b0: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68  t insure that th
39c0: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
39d0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
39e0: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
39f0: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
3a00: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3a10: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
3a20: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3a30: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74  t not close [dat
3a40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a50: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  ] specified by.*
3a60: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70  *      the 1st p
3a70: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3a80: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
3a90: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3aa0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
3ab0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
3ac0: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64  ion must not mod
3ad0: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74  ify the SQL stat
3ae0: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65  ement text passe
3af0: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74  d into.**      t
3b00: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
3b10: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
3b20: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
3b30: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
3b40: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ng..** </ul>.*/.
3b50: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
3b60: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3b90: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
3ba0: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
3bb0: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
3be0: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69  evaluated */.  i
3bf0: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
3c00: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
3c10: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
3c20: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
3c30: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3c60: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
3c70: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
3c80: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **errmsg   
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
3cb0: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
3cc0: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
3cd0: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
3ce0: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
3cf0: 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20  ORDS: SQLITE_OK 
3d00: 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72  {error code} {er
3d10: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
3d20: 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20  YWORDS: {result 
3d30: 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f  code} {result co
3d40: 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  des}.**.** Many 
3d50: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
3d60: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
3d70: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
3d80: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
3d90: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64  n.** here in ord
3da0: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73  er to indicate s
3db0: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
3dc0: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
3dd0: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
3de0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
3df0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
3e00: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
3e10: 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  so: [SQLITE_IOER
3e20: 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
3e30: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c  d result codes],
3e40: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  .** [sqlite3_vta
3e50: 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
3e60: 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43   [SQLITE_ROLLBAC
3e70: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
3e80: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
3e90: 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20  LITE_OK         
3ea0: 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73    0   /* Success
3eb0: 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a  ful result */./*
3ec0: 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72   beginning-of-er
3ed0: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65  ror-codes */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f  fine SQLITE_ERRO
3ef0: 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20  R        1   /* 
3f00: 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73  SQL error or mis
3f10: 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f  sing database */
3f20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f30: 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20  INTERNAL     2  
3f40: 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67   /* Internal log
3f50: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69  ic error in SQLi
3f60: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
3f70: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20  LITE_PERM       
3f80: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20    3   /* Access 
3f90: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65  permission denie
3fa0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
3fb0: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20  ITE_ABORT       
3fc0: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b   4   /* Callback
3fd0: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74   routine request
3fe0: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23  ed an abort */.#
3ff0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
4000: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f  SY         5   /
4010: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66  * The database f
4020: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ile is locked */
4030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4040: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20  LOCKED       6  
4050: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74   /* A table in t
4060: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c  he database is l
4070: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
4080: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20   SQLITE_NOMEM   
4090: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61       7   /* A ma
40a0: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f  lloc() failed */
40b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
40c0: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20  READONLY     8  
40d0: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77   /* Attempt to w
40e0: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20  rite a readonly 
40f0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
4100: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
4110: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f  RUPT    9   /* O
4120: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61  peration termina
4130: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
4140: 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65  nterrupt()*/.#de
4150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4160: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20  R       10   /* 
4170: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73  Some kind of dis
4180: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75  k I/O error occu
4190: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rred */.#define 
41a0: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20  SQLITE_CORRUPT  
41b0: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64     11   /* The d
41c0: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61  atabase disk ima
41d0: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20  ge is malformed 
41e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
41f0: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32  E_NOTFOUND    12
4200: 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70     /* Unknown op
4210: 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f  code in sqlite3_
4220: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a  file_control() *
4230: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4240: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20  _FULL        13 
4250: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66    /* Insertion f
4260: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61  ailed because da
4270: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a  tabase is full *
4280: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4290: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20  _CANTOPEN    14 
42a0: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f    /* Unable to o
42b0: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
42c0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
42d0: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c   SQLITE_PROTOCOL
42e0: 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61      15   /* Data
42f0: 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63  base lock protoc
4300: 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  ol error */.#def
4310: 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59  ine SQLITE_EMPTY
4320: 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44         16   /* D
4330: 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79  atabase is empty
4340: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4350: 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31  TE_SCHEMA      1
4360: 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  7   /* The datab
4370: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
4380: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4390: 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20  LITE_TOOBIG     
43a0: 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20   18   /* String 
43b0: 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20  or BLOB exceeds 
43c0: 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64  size limit */.#d
43d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
43e0: 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a  STRAINT  19   /*
43f0: 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f   Abort due to co
4400: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
4410: 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  on */.#define SQ
4420: 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20  LITE_MISMATCH   
4430: 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79   20   /* Data ty
4440: 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23  pe mismatch */.#
4450: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
4460: 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f  SUSE      21   /
4470: 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69  * Library used i
4480: 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64  ncorrectly */.#d
4490: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c  efine SQLITE_NOL
44a0: 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a  FS       22   /*
44b0: 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65   Uses OS feature
44c0: 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20  s not supported 
44d0: 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69  on host */.#defi
44e0: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20  ne SQLITE_AUTH  
44f0: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75        23   /* Au
4500: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69  thorization deni
4510: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4520: 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20  LITE_FORMAT     
4530: 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61   24   /* Auxilia
4540: 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d  ry database form
4550: 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  at error */.#def
4560: 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45  ine SQLITE_RANGE
4570: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32         25   /* 2
4580: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
4590: 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74  sqlite3_bind out
45a0: 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65   of range */.#de
45b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41  fine SQLITE_NOTA
45c0: 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20  DB      26   /* 
45d0: 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74  File opened that
45e0: 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
45f0: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4600: 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20  ne SQLITE_ROW   
4610: 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71        100  /* sq
4620: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4630: 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61   another row rea
4640: 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  dy */.#define SQ
4650: 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20  LITE_DONE       
4660: 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33   101  /* sqlite3
4670: 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69  _step() has fini
4680: 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a  shed executing *
4690: 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f  /./* end-of-erro
46a0: 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a  r-codes */../*.*
46b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65  * CAPI3REF: Exte
46c0: 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
46d0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
46e0: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
46f0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65  ode} {extended e
4700: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
4710: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
4720: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  ed result code} 
4730: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
4740: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e   codes}.**.** In
4750: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
4760: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
4770: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
4780: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
4790: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
47a0: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
47b0: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
47c0: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
47d0: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
47e0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
47f0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
4800: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
4810: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
4820: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
4830: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
4840: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
4850: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
4860: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
4870: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
4880: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
4890: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
48a0: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
48b0: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
48c0: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
48d0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
48e0: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
48f0: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
4900: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
4910: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
4920: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  rs. The extended
4930: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4940: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
4950: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
4960: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
4970: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
4980: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
4990: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
49a0: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a  t_codes()] API..
49b0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
49c0: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65  e available exte
49d0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
49e0: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72  s are listed her
49f0: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78  e..** One may ex
4a00: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
4a10: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
4a20: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
4a30: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
4a40: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
4a50: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
4a60: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4a70: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
4a80: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
4a90: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
4aa0: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
4ab0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
4ac0: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c   SQLITE_OK resul
4ad0: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65  t code will neve
4ae0: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20  r be extended.  
4af0: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a  It will always.*
4b00: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72  * be exactly zer
4b10: 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  o..*/.#define SQ
4b20: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
4b30: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4b40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
4b50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4b60: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
4b70: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c  READ        (SQL
4b80: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c  ITE_IOERR | (2<<
4b90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ba0: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20  TE_IOERR_WRITE  
4bb0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4bc0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
4bd0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4be0: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
4bf0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4c00: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
4c10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4c20: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
4c30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4c40: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
4c50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c60: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
4c70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4c80: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a  IOERR | (6<<8)).
4c90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4ca0: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20  OERR_FSTAT      
4cb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4cc0: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
4cd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ce0: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
4cf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4d00: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
4d10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d20: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
4d30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d40: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
4d50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4d60: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
4d70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4d80: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65  R | (10<<8)).#de
4d90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4da0: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  R_BLOCKED       
4db0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4dc0: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
4dd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4de0: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
4df0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4e00: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65  R | (12<<8)).#de
4e10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e20: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20  R_ACCESS        
4e30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4e40: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65  R | (13<<8)).#de
4e50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e60: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c  R_CHECKRESERVEDL
4e70: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52  OCK (SQLITE_IOER
4e80: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65  R | (14<<8)).#de
4e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ea0: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  R_LOCK          
4eb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4ec0: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65  R | (15<<8)).#de
4ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ee0: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
4ef0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f00: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65  R | (16<<8)).#de
4f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f20: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20  R_DIR_CLOSE     
4f30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f40: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65  R | (17<<8)).#de
4f50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f60: 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20  R_SHMOPEN       
4f70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f80: 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65  R | (18<<8)).#de
4f90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4fa0: 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20  R_SHMSIZE       
4fb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4fc0: 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65  R | (19<<8)).#de
4fd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4fe0: 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20  R_SHMLOCK       
4ff0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5000: 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65  R | (20<<8)).#de
5010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5020: 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20  R_SHMMAP        
5030: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5040: 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65  R | (21<<8)).#de
5050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5060: 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20  R_SEEK          
5070: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5080: 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65  R | (22<<8)).#de
5090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
50a0: 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  ED_SHAREDCACHE  
50b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
50c0: 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64  ED |  (1<<8)).#d
50d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
50e0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
50f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5100: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  Y   |  (1<<8)).#
5110: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5120: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5130: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5140: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5160: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
5170: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5180: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5190: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
51a0: 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20  E_CORRUPT_VTAB  
51b0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
51c0: 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c  E_CORRUPT | (1<<
51d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
51e0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f  TE_READONLY_RECO
51f0: 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c 49  VERY       (SQLI
5200: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31  TE_READONLY | (1
5210: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5220: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41  LITE_READONLY_CA
5230: 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51  NTLOCK       (SQ
5240: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
5250: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5260: 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c  SQLITE_ABORT_ROL
5270: 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28  LBACK          (
5280: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28  SQLITE_ABORT | (
5290: 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  2<<8))../*.** CA
52a0: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f  PI3REF: Flags Fo
52b0: 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72  r File Open Oper
52c0: 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ations.**.** The
52d0: 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72  se bit values ar
52e0: 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
52f0: 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64  se in the.** 3rd
5300: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5310: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  e [sqlite3_open_
5320: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
5330: 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74  and.** in the 4t
5340: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
5350: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
5360: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a  xOpen] method..*
5370: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5380: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20  _OPEN_READONLY  
5390: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
53a0: 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  1  /* Ok for sql
53b0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
53c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
53d0: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
53e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
53f0: 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  2  /* Ok for sql
5400: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5410: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5420: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20  _OPEN_CREATE    
5430: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5440: 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  4  /* Ok for sql
5450: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5460: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5470: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
5480: 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30  OSE    0x0000000
5490: 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  8  /* VFS only *
54a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
54b0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
54c0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
54d0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
54e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
54f0: 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20  _OPEN_AUTOPROXY 
5500: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
5510: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5520: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5530: 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20  _OPEN_URI       
5540: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
5550: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
5560: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5570: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5580: 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20  _OPEN_MEMORY    
5590: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
55a0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
55b0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
55c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
55d0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20  _OPEN_MAIN_DB   
55e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
55f0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5600: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5610: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20  _OPEN_TEMP_DB   
5620: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
5630: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5640: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5650: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
5660: 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30  DB     0x0000040
5670: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5680: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5690: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
56a0: 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30  AL     0x0000080
56b0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
56c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
56d0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
56e0: 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30  AL     0x0000100
56f0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5700: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5710: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
5720: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
5730: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5740: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5750: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
5760: 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30  RNAL   0x0000400
5770: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5780: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5790: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20  _OPEN_NOMUTEX   
57a0: 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30         0x0000800
57b0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
57c0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
57d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
57e0: 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20  _OPEN_FULLMUTEX 
57f0: 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30         0x0001000
5800: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
5810: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5820: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5830: 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
5840: 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30  E      0x0002000
5850: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
5860: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5870: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5880: 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
5890: 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30  HE     0x0004000
58a0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
58b0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
58c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
58d0: 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20  _OPEN_WAL       
58e0: 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30         0x0008000
58f0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5900: 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20  /../* Reserved: 
5910: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5920: 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30          0x00F000
5930: 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00 */../*.** CAP
5940: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
5950: 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a  aracteristics.**
5960: 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43  .** The xDeviceC
5970: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
5980: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71  ethod of the [sq
5990: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
59a0: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75  ].** object retu
59b0: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77  rns an integer w
59c0: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72  hich is a vector
59d0: 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a   of the these.**
59e0: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72   bit values expr
59f0: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61  essing I/O chara
5a00: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68  cteristics of th
5a10: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a  e mass storage.*
5a20: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f  * device that ho
5a30: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61  lds the file tha
5a40: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  t the [sqlite3_i
5a50: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65  o_methods].** re
5a60: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54  fers to..**.** T
5a70: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
5a80: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
5a90: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
5aa0: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
5ab0: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
5ac0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
5ad0: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
5ae0: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
5af0: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
5b00: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
5b10: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
5b20: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
5b30: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
5b40: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
5b50: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
5b60: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
5b70: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
5b80: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
5b90: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
5ba0: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
5bb0: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
5bc0: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
5bd0: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
5be0: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
5bf0: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
5c00: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
5c10: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
5c20: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
5c30: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
5c40: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
5c50: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
5c60: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
5c70: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
5c80: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
5c90: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
5ca0: 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54  te().  The SQLIT
5cb0: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
5cc0: 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70  E_OVERWRITE prop
5cd0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
5ce0: 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20  ** after reboot 
5cf0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73  following a cras
5d00: 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c  h or power loss,
5d10: 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20   the only bytes 
5d20: 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61  in a.** file tha
5d30: 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61  t were written a
5d40: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
5d50: 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61  n level might ha
5d60: 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e  ve changed.** an
5d70: 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20  d that adjacent 
5d80: 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65  bytes, even byte
5d90: 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  s within the sam
5da0: 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20  e sector are.** 
5db0: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
5dc0: 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23   unchanged..*/.#
5dd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5de0: 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  CAP_ATOMIC      
5df0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5e00: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
5e10: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5e20: 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20  C512            
5e30: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
5e40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5e50: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20  P_ATOMIC1K      
5e60: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5e70: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
5e80: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
5e90: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
5ea0: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
5eb0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5ec0: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
5ed0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
5ee0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5ef0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20  _IOCAP_ATOMIC8K 
5f00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5f10: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65  00000020.#define
5f20: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5f30: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20  OMIC16K         
5f40: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a       0x00000040.
5f50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5f60: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20  OCAP_ATOMIC32K  
5f70: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5f80: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
5f90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5fa0: 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20  IC64K           
5fb0: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
5fc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5fd0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20  AP_SAFE_APPEND  
5fe0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5ff0: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
6000: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
6010: 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  TIAL            
6020: 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66   0x00000400.#def
6030: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6040: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
6050: 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38  N_OPEN  0x000008
6060: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6070: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
6080: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30  E_OVERWRITE    0
6090: 78 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a  x00001000../*.**
60a0: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20   CAPI3REF: File 
60b0: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a  Locking Levels.*
60c0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
60d0: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
60e0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
60f0: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  the second.** ar
6100: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20  gument to calls 
6110: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20  it makes to the 
6120: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
6130: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a  ock() methods.**
6140: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
6150: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6160: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
6170: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20  QLITE_LOCK_NONE 
6180: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
6190: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  ne SQLITE_LOCK_S
61a0: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23  HARED        1.#
61b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
61c0: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20  CK_RESERVED     
61d0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
61e0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20  E_LOCK_PENDING  
61f0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
6200: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
6210: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a  SIVE     4../*.*
6220: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63  * CAPI3REF: Sync
6230: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65  hronization Type
6240: 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65   Flags.**.** Whe
6250: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
6260: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74   the xSync() met
6270: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71  hod of an.** [sq
6280: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6290: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73  ] object it uses
62a0: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
62b0: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67  f.** these integ
62c0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
62d0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
62e0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
62f0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
6300: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73  AONLY flag is us
6310: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  ed, it means tha
6320: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70  t the.** sync op
6330: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65  eration only nee
6340: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  ds to flush data
6350: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65   to mass storage
6360: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f  .  Inode.** info
6370: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74  rmation need not
6380: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20   be flushed. If 
6390: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
63a0: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a  its of the flag.
63b0: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ** equal SQLITE_
63c0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61  SYNC_NORMAL, tha
63d0: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e  t means to use n
63e0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65  ormal fsync() se
63f0: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74  mantics..** If t
6400: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
6410: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ts equal SQLITE_
6420: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20  SYNC_FULL, that 
6430: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
6440: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
6450: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
6460: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a  of fsync()..**.*
6470: 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65  * Do not confuse
6480: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
6490: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
64a0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
64b0: 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  gs.** with the [
64c0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
64d0: 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b  us]=NORMAL and [
64e0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
64f0: 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74  us]=FULL.** sett
6500: 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63  ings.  The [sync
6510: 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20  hronous pragma] 
6520: 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20  determines when 
6530: 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20  calls to the.** 
6540: 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64  xSync VFS method
6550: 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69   occur and appli
6560: 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72  es uniformly acr
6570: 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d  oss all platform
6580: 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  s..** The SQLITE
6590: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
65a0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
65b0: 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e  L flags determin
65c0: 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74  e how.** energet
65d0: 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f  ic or rigorous o
65e0: 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73  r forceful the s
65f0: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ync operations a
6600: 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d  re and.** only m
6610: 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65  ake a difference
6620: 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20   on Mac OSX for 
6630: 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69  the default SQLi
6640: 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69  te code..** (Thi
6650: 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70  rd-party VFS imp
6660: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67  lementations mig
6670: 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65  ht also make the
6680: 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20   distinction.** 
6690: 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53  between SQLITE_S
66a0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
66b0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
66c0: 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a   but among the.*
66d0: 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  * operating syst
66e0: 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70  ems natively sup
66f0: 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
6700: 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a  , only Mac OSX.*
6710: 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68  * cares about th
6720: 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a  e difference.).*
6730: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6740: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20  _SYNC_NORMAL    
6750: 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66      0x00002.#def
6760: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
6770: 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78  FULL          0x
6780: 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51  00003.#define SQ
6790: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
67a0: 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a  LY      0x00010.
67b0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
67c0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70   OS Interface Op
67d0: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a  en File Handle.*
67e0: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
67f0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
6800: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
6810: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a   file in the .**
6820: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
6830: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
6840: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  er].  Individual
6850: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a   OS interface.**
6860: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
6870: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f   will.** want to
6880: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f   subclass this o
6890: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69  bject by appendi
68a0: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  ng additional fi
68b0: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69  elds.** for thei
68c0: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20  r own use.  The 
68d0: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69  pMethods entry i
68e0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
68f0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
6900: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
6910: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65   that defines me
6920: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72  thods for perfor
6930: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72  ming.** I/O oper
6940: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70  ations on the op
6950: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65  en file..*/.type
6960: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
6970: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f  e3_file sqlite3_
6980: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c  file;.struct sql
6990: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f  ite3_file {.  co
69a0: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
69b0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70  e3_io_methods *p
69c0: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74  Methods;  /* Met
69d0: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e  hods for an open
69e0: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a   file */.};../*.
69f0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
6a00: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56  Interface File V
6a10: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f  irtual Methods O
6a20: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72  bject.**.** Ever
6a30: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79  y file opened by
6a40: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
6a50: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
6a60: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20  populates an.** 
6a70: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
6a80: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20  bject (or, more 
6a90: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63  commonly, a subc
6aa0: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  lass of the.** [
6ab0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
6ac0: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69  ject) with a poi
6ad0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
6ae0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
6af0: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  ct..** This obje
6b00: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d  ct defines the m
6b10: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70  ethods used to p
6b20: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f  erform various o
6b30: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61  perations.** aga
6b40: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69  inst the open fi
6b50: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  le represented b
6b60: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  y the [sqlite3_f
6b70: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  ile] object..**.
6b80: 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74  ** If the [sqlit
6b90: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
6ba0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
6bb0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
6bc0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
6bd0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
6be0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
6bf0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6c00: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
6c10: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
6c20: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b  ed even if the [
6c30: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
6c40: 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74  n] reported that
6c50: 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65   it failed.  The
6c60: 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20  .** only way to 
6c70: 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74  prevent a call t
6c80: 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69  o xClose followi
6c90: 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c  ng a failed [sql
6ca0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a  ite3_vfs.xOpen].
6cb0: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73  ** is for the [s
6cc0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
6cd0: 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c  ] to set the sql
6ce0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
6cf0: 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f  ds element.** to
6d00: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
6d10: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
6d20: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20  to xSync may be 
6d30: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53  one of [SQLITE_S
6d40: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a  YNC_NORMAL] or.*
6d50: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  * [SQLITE_SYNC_F
6d60: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ULL].  The first
6d70: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e   choice is the n
6d80: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a  ormal fsync()..*
6d90: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f  * The second cho
6da0: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20  ice is a Mac OS 
6db0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
6dc0: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53  .  The [SQLITE_S
6dd0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a  YNC_DATAONLY].**
6de0: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65   flag may be ORe
6df0: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  d in to indicate
6e00: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
6e10: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a  ata of the file.
6e20: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69  ** and not its i
6e30: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65  node needs to be
6e40: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   synced..**.** T
6e50: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  he integer value
6e60: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64  s to xLock() and
6e70: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f   xUnlock() are o
6e80: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ne of.** <ul>.**
6e90: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
6ea0: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69  CK_NONE],.** <li
6eb0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  > [SQLITE_LOCK_S
6ec0: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  HARED],.** <li> 
6ed0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
6ee0: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  ERVED],.** <li> 
6ef0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
6f00: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  DING], or.** <li
6f10: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  > [SQLITE_LOCK_E
6f20: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f  XCLUSIVE]..** </
6f30: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69  ul>.** xLock() i
6f40: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ncreases the loc
6f50: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63  k. xUnlock() dec
6f60: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
6f70: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65  .** The xCheckRe
6f80: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74  servedLock() met
6f90: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68  hod checks wheth
6fa0: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  er any database 
6fb0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65  connection,.** e
6fc0: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72  ither in this pr
6fd0: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
6fe0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
6ff0: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53  is holding a RES
7000: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
7010: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
7020: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
7030: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
7040: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
7050: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
7060: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e  false otherwise.
7070: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65  .**.** The xFile
7080: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64  Control() method
7090: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e   is a generic in
70a0: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c  terface that all
70b0: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46  ows custom.** VF
70c0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
70d0: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f  s to directly co
70e0: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69  ntrol an open fi
70f0: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
7100: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
7110: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
7120: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ce.  The second 
7130: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73  "op" argument is
7140: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f   an.** integer o
7150: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72  pcode.  The thir
7160: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
7170: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
7180: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70  intended to.** p
7190: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74  oint to a struct
71a0: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e  ure that may con
71b0: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f  tain arguments o
71c0: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68  r space in which
71d0: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74   to.** write ret
71e0: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74  urn values.  Pot
71f0: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20  ential uses for 
7200: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
7210: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74  ight be.** funct
7220: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62  ions to enable b
7230: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69  locking locks wi
7240: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20  th timeouts, to 
7250: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f  change the.** lo
7260: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28  cking strategy (
7270: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75  for example to u
7280: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b  se dot-file lock
7290: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a  s), to inquire.*
72a0: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74  * about the stat
72b0: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72  us of a lock, or
72c0: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20   to break stale 
72d0: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69  locks.  The SQLi
72e0: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72  te.** core reser
72f0: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20  ves all opcodes 
7300: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f  less than 100 fo
7310: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a  r its own use..*
7320: 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  * A [SQLITE_FCNT
7330: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69  L_LOCKSTATE | li
7340: 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c  st of opcodes] l
7350: 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20  ess than 100 is 
7360: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70  available..** Ap
7370: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
7380: 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20  define a custom 
7390: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
73a0: 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f  hod should use o
73b0: 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65  pcodes.** greate
73c0: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76  r than 100 to av
73d0: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20  oid conflicts.  
73e0: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
73f0: 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ons should.** re
7400: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  turn [SQLITE_NOT
7410: 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20  FOUND] for file 
7420: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20  control opcodes 
7430: 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
7440: 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a  .** recognize..*
7450: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72  *.** The xSector
7460: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65  Size() method re
7470: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72  turns the sector
7480: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20   size of the.** 
7490: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65  device that unde
74a0: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20  rlies the file. 
74b0: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   The sector size
74c0: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d   is the.** minim
74d0: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61  um write that ca
74e0: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77  n be performed w
74f0: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e  ithout disturbin
7500: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73  g.** other bytes
7510: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54   in the file.  T
7520: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
7530: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d  teristics().** m
7540: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
7550: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72  bit vector descr
7560: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20  ibing behaviors 
7570: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  of the.** underl
7580: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a  ying device:.**.
7590: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
75a0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
75b0: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OMIC].** <li> [S
75c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
75d0: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC512].** <li> [
75e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
75f0: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC1K].** <li> [
7600: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7610: 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC2K].** <li> [
7620: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7630: 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC4K].** <li> [
7640: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7650: 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC8K].** <li> [
7660: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7670: 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC16K].** <li> 
7680: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7690: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC32K].** <li>
76a0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
76b0: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC64K].** <li
76c0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
76d0: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20  SAFE_APPEND].** 
76e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
76f0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a  AP_SEQUENTIAL].*
7700: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
7710: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
7720: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
7730: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
7740: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
7750: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
7760: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
7770: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
7780: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
7790: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
77a0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
77b0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
77c0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
77d0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
77e0: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
77f0: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
7800: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
7810: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
7820: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
7830: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
7840: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
7850: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
7860: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
7870: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
7880: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
7890: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
78a0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
78b0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
78c0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
78d0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
78e0: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
78f0: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
7900: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
7910: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
7920: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
7930: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
7940: 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52  e()..**.** If xR
7950: 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51  ead() returns SQ
7960: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
7970: 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c  _READ it must al
7980: 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68  so fill.** in th
7990: 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e  e unread portion
79a0: 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  s of the buffer 
79b0: 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56  with zeros.  A V
79c0: 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73  FS that.** fails
79d0: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
79e0: 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20  ort reads might 
79f0: 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48  seem to work.  H
7a00: 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75  owever,.** failu
7a10: 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  re to zero-fill 
7a20: 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c  short reads will
7a30: 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64   eventually lead
7a40: 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20   to.** database 
7a50: 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74  corruption..*/.t
7a60: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
7a70: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7a80: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
7a90: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
7aa0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b  te3_io_methods {
7ab0: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
7ac0: 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29  .  int (*xClose)
7ad0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
7ae0: 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28  .  int (*xRead)(
7af0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76  sqlite3_file*, v
7b00: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20  oid*, int iAmt, 
7b10: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
7b20: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57  fst);.  int (*xW
7b30: 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  rite)(sqlite3_fi
7b40: 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  le*, const void*
7b50: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
7b60: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
7b70: 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63  ;.  int (*xTrunc
7b80: 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ate)(sqlite3_fil
7b90: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
7ba0: 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  4 size);.  int (
7bb0: 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xSync)(sqlite3_
7bc0: 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73  file*, int flags
7bd0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
7be0: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
7bf0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
7c00: 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e  64 *pSize);.  in
7c10: 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74  t (*xLock)(sqlit
7c20: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
7c30: 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29    int (*xUnlock)
7c40: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7c50: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  int);.  int (*xC
7c60: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
7c70: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7c80: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
7c90: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e    int (*xFileCon
7ca0: 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69  trol)(sqlite3_fi
7cb0: 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69  le*, int op, voi
7cc0: 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20  d *pArg);.  int 
7cd0: 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73  (*xSectorSize)(s
7ce0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
7cf0: 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68   int (*xDeviceCh
7d00: 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73  aracteristics)(s
7d10: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
7d20: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
7d30: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
7d40: 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69  version 1 */.  i
7d50: 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71  nt (*xShmMap)(sq
7d60: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7d70: 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20   iPg, int pgsz, 
7d80: 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69  int, void volati
7d90: 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  le**);.  int (*x
7da0: 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  ShmLock)(sqlite3
7db0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73  _file*, int offs
7dc0: 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66  et, int n, int f
7dd0: 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a  lags);.  void (*
7de0: 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c  xShmBarrier)(sql
7df0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
7e00: 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28  nt (*xShmUnmap)(
7e10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7e20: 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a  nt deleteFlag);.
7e30: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
7e40: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
7e50: 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20   version 2 */.  
7e60: 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65  /* Additional me
7e70: 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64  thods may be add
7e80: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
7e90: 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  eases */.};../*.
7ea0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61  ** CAPI3REF: Sta
7eb0: 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72  ndard File Contr
7ec0: 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a  ol Opcodes.**.**
7ed0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
7ee0: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63  onstants are opc
7ef0: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69  odes for the xFi
7f00: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
7f10: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
7f20: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
7f30: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74  object and for t
7f40: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
7f50: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
7f60: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
7f70: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
7f80: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63  L_LOCKSTATE] opc
7f90: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
7fa0: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
7fb0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
7fc0: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
7fd0: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69  ol method to wri
7fe0: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  te the current s
7ff0: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c  tate of.** the l
8000: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c  ock (one of [SQL
8010: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20  ITE_LOCK_NONE], 
8020: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
8030: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  RED],.** [SQLITE
8040: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
8050: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
8060: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49  NDING], or [SQLI
8070: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
8080: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69  E]).** into an i
8090: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20  nteger that the 
80a0: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f  pArg argument po
80b0: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61  ints to. This ca
80c0: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75  pability.** is u
80d0: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
80e0: 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ng and only need
80f0: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
8100: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
8110: 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64  ST.** is defined
8120: 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  ..** <ul>.** <li
8130: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
8140: 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54  SIZE_HINT]].** T
8150: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8160: 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f  _SIZE_HINT] opco
8170: 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51  de is used by SQ
8180: 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65  Lite to give the
8190: 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20   VFS.** layer a 
81a0: 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67  hint of how larg
81b0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
81c0: 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f  ile will grow to
81d0: 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a   be during the.*
81e0: 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  * current transa
81f0: 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e  ction.  This hin
8200: 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  t is not guarant
8210: 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61  eed to be accura
8220: 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20  te but it.** is 
8230: 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68  often close.  Th
8240: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53  e underlying VFS
8250: 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f   might choose to
8260: 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74   preallocate dat
8270: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70  abase.** file sp
8280: 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69  ace based on thi
8290: 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20  s hint in order 
82a0: 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74  to help writes t
82b0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
82c0: 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65  * file run faste
82d0: 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  r..**.** <li>[[S
82e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
82f0: 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20  K_SIZE]].** The 
8300: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
8310: 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65  UNK_SIZE] opcode
8320: 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75   is used to requ
8330: 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53  est that the VFS
8340: 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20  .** extends and 
8350: 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61  truncates the da
8360: 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63  tabase file in c
8370: 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20  hunks of a size 
8380: 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
8390: 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f  the user. The fo
83a0: 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
83b0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
83c0: 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64  ontrol()] should
83d0: 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e   .** point to an
83e0: 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69   integer (type i
83f0: 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  nt) containing t
8400: 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a  he new chunk-siz
8410: 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20  e to use.** for 
8420: 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61  the nominated da
8430: 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69  tabase. Allocati
8440: 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ng database file
8450: 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a   space in large.
8460: 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31  ** chunks (say 1
8470: 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d  MB at a time), m
8480: 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73  ay reduce file-s
8490: 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74  ystem fragmentat
84a0: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f  ion and.** impro
84b0: 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f  ve performance o
84c0: 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a  n some systems..
84d0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
84e0: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
84f0: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b  INTER]].** The [
8500: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
8510: 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  E_POINTER] opcod
8520: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
8530: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
8540: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
8550: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
8560: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
8570: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
8580: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
8590: 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c  n.  See the [sql
85a0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
85b0: 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  l()] documentati
85c0: 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  on for.** additi
85d0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
85e0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
85f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
8600: 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54  OMITTED]].** ^(T
8610: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8620: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f  _SYNC_OMITTED] o
8630: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
8640: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
8650: 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73  .** SQLite and s
8660: 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73  ent to all VFSes
8670: 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63   in place of a c
8680: 61 6c 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63  all to the xSync
8690: 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20   method.** when 
86a0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
86b0: 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41  nection has [PRA
86c0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
86d0: 20 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a   set to OFF.)^.*
86e0: 2a 20 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a  * Some specializ
86f0: 65 64 20 56 46 53 65 73 20 6e 65 65 64 20 74 68  ed VFSes need th
8700: 69 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64  is signal in ord
8710: 65 72 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f  er to operate co
8720: 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20  rrectly.** when 
8730: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
8740: 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e  ous | PRAGMA syn
8750: 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73  chronous=OFF] is
8760: 20 73 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a   set, but most .
8770: 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20  ** VFSes do not 
8780: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
8790: 20 61 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65   and should sile
87a0: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
87b0: 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c   opcode..** Appl
87c0: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
87d0: 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65  not call [sqlite
87e0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
87f0: 5d 20 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f  ] with this.** o
8800: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
8810: 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68  o may disrupt th
8820: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  e operation of t
8830: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
8840: 46 53 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20  FSes.** that do 
8850: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
8860: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
8870: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
8880: 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20  RETRY]].** ^The 
8890: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
88a0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70  N32_AV_RETRY] op
88b0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
88c0: 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61  configure automa
88d0: 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75  tic.** retry cou
88e0: 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c  nts and interval
88f0: 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69  s for certain di
8900: 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  sk I/O operation
8910: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e  s for the.** win
8920: 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72  dows [VFS] in or
8930: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72  der to provide r
8940: 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65  obustness in the
8950: 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20   presence of.** 
8960: 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72  anti-virus progr
8970: 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ams.  By default
8980: 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46  , the windows VF
8990: 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c  S will retry fil
89a0: 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20  e read,.** file 
89b0: 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20  write, and file 
89c0: 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e  delete operation
89d0: 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73  s up to 10 times
89e0: 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a  , with a delay.*
89f0: 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63  * of 25 millisec
8a00: 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20  onds before the 
8a10: 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20  first retry and 
8a20: 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69  with the delay i
8a30: 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20  ncreasing.** by 
8a40: 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35  an additional 25
8a50: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69   milliseconds wi
8a60: 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65  th each subseque
8a70: 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a  nt retry.  This.
8a80: 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73  ** opcode allows
8a90: 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65   these two value
8aa0: 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e  s (10 retries an
8ab0: 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  d 25 millisecond
8ac0: 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74  s of delay).** t
8ad0: 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20  o be adjusted.  
8ae0: 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63  The values are c
8af0: 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64  hanged for all d
8b00: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
8b10: 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68  ons.** within th
8b20: 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20  e same process. 
8b30: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
8b40: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
8b50: 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a   array of two.**
8b60: 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20   integers where 
8b70: 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65  the first intege
8b80: 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72  r i the new retr
8b90: 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20  y count and the 
8ba0: 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65  second.** intege
8bb0: 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20  r is the delay. 
8bc0: 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67   If either integ
8bd0: 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
8be0: 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67  then the setting
8bf0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
8c00: 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74  ed but instead t
8c10: 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
8c20: 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69  f that setting i
8c30: 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74  s written.** int
8c40: 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72  o the array entr
8c50: 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20  y, allowing the 
8c60: 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65  current retry se
8c70: 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20  ttings to be.** 
8c80: 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54  interrogated.  T
8c90: 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d  he zDbName param
8ca0: 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e  eter is ignored.
8cb0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8cc0: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
8cd0: 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20  T_WAL]].** ^The 
8ce0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
8cf0: 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64  RSIST_WAL] opcod
8d00: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
8d10: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
8d20: 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c   persistent [WAL
8d30: 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c   | Write Ahead L
8d40: 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79  og] setting.  By
8d50: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75   default, the au
8d60: 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65  xiliary.** write
8d70: 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73   ahead log and s
8d80: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
8d90: 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e  es used for tran
8da0: 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a  saction control.
8db0: 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ** are automatic
8dc0: 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65  ally deleted whe
8dd0: 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e  n the latest con
8de0: 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64  nection to the d
8df0: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65  atabase.** close
8e00: 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73  s.  Setting pers
8e10: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
8e20: 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c  causes those fil
8e30: 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66  es to persist af
8e40: 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50  ter.** close.  P
8e50: 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69  ersisting the fi
8e60: 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68  les is useful wh
8e70: 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  en other process
8e80: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a  es that do not.*
8e90: 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72  * have write per
8ea0: 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64  mission on the d
8eb0: 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e  irectory contain
8ec0: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
8ed0: 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f   file want.** to
8ee0: 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61   read the databa
8ef0: 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20  se file, as the 
8f00: 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d  WAL and shared m
8f10: 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74  emory files must
8f20: 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64   exist.** in ord
8f30: 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  er for the datab
8f40: 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62  ase to be readab
8f50: 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  le.  The fourth 
8f60: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
8f70: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
8f80: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
8f90: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
8fa0: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
8fb0: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
8fc0: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
8fd0: 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73   to disable pers
8fe0: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
8ff0: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70  or 1 to enable p
9000: 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c  ersistent.** WAL
9010: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
9020: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
9030: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
9040: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
9050: 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72  rrent.** WAL per
9060: 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67  sistence setting
9070: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9080: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
9090: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d  SAFE_OVERWRITE]]
90a0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
90b0: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
90c0: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
90d0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
90e0: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
90f0: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f  * persistent "po
9100: 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74  wersafe-overwrit
9110: 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74  e" or "PSOW" set
9120: 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20  ting.  The PSOW 
9130: 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72  setting.** deter
9140: 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54  mines the [SQLIT
9150: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
9160: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74  E_OVERWRITE] bit
9170: 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69   of the.** xDevi
9180: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
9190: 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66  s methods. The f
91a0: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
91b0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
91c0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
91d0: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
91e0: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
91f0: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
9200: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
9210: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
9220: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  e zero-damage mo
9230: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
9240: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a  e zero-damage.**
9250: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
9260: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
9270: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
9280: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
9290: 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61  rrent.** zero-da
92a0: 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e  mage mode settin
92b0: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
92c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
92d0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
92e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
92f0: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
9300: 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51  is invoked by SQ
9310: 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69  Lite after openi
9320: 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72  ng.** a write tr
9330: 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64  ansaction to ind
9340: 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65  icate that, unle
9350: 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20  ss it is rolled 
9360: 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a  back for some.**
9370: 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74   reason, the ent
9380: 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ire database fil
9390: 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72  e will be overwr
93a0: 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72  itten by the cur
93b0: 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63  rent .** transac
93c0: 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73  tion. This is us
93d0: 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65  ed by VACUUM ope
93e0: 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c  rations..**.** <
93f0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9400: 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e  L_VFSNAME]].** ^
9410: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9420: 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64  L_VFSNAME] opcod
9430: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
9440: 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65   obtain the name
9450: 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53  s of.** all [VFS
9460: 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73  es] in the VFS s
9470: 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73  tack.  The names
9480: 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20   are of all VFS 
9490: 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a  shims and the.**
94a0: 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65   final bottom-le
94b0: 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74  vel VFS are writ
94c0: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
94d0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a  obtained from .*
94e0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
94f0: 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73  c()] and the res
9500: 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e  ult is stored in
9510: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
9520: 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ble.** that the 
9530: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
9540: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   of [sqlite3_fil
9550: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69  e_control()] poi
9560: 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63  nts to..** The c
9570: 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73  aller is respons
9580: 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67  ible for freeing
9590: 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e   the memory when
95a0: 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a   done.  As with.
95b0: 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74  ** all file-cont
95c0: 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  rol actions, the
95d0: 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74  re is no guarant
95e0: 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c  ee that this wil
95f0: 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f  l actually.** do
9600: 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c   anything.  Call
9610: 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69  ers should initi
9620: 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20  alize the char* 
9630: 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55  variable to a NU
9640: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  LL.** pointer in
9650: 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d   case this file-
9660: 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69  control is not i
9670: 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69  mplemented.  Thi
9680: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  s file-control.*
9690: 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  * is intended fo
96a0: 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65  r diagnostic use
96b0: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   only..**.** <li
96c0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
96d0: 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65  PRAGMA]].** ^Whe
96e0: 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d  never a [PRAGMA]
96f0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61   statement is pa
9700: 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45  rsed, an [SQLITE
9710: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a  _FCNTL_PRAGMA] .
9720: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
9730: 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f  is sent to the o
9740: 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  pen [sqlite3_fil
9750: 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73  e] object corres
9760: 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68  ponding.** to th
9770: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9780: 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61  to which the pra
9790: 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65  gma statement re
97a0: 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d  fers. ^The argum
97b0: 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53  ent.** to the [S
97c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
97d0: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
97e0: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a   is an array of.
97f0: 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  ** pointers to s
9800: 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20  trings (char**) 
9810: 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63  in which the sec
9820: 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74  ond element of t
9830: 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74  he array.** is t
9840: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70  he name of the p
9850: 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68  ragma and the th
9860: 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74  ird element is t
9870: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  he argument to t
9880: 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20  he.** pragma or 
9890: 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67  NULL if the prag
98a0: 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65  ma has no argume
98b0: 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  nt.  ^The handle
98c0: 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c  r for an.** [SQL
98d0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
98e0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63  ] file control c
98f0: 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61  an optionally ma
9900: 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65  ke the first ele
9910: 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63  ment.** of the c
9920: 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70  har** argument p
9930: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
9940: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
9950: 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
9960: 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75  )].** or the equ
9970: 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74  ivalent and that
9980: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63   string will bec
9990: 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ome the result o
99a0: 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a  f the pragma or.
99b0: 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ** the error mes
99c0: 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67  sage if the prag
99d0: 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68  ma fails. ^If th
99e0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
99f0: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
9a00: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
9a10: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
9a20: 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a  ], then normal .
9a30: 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63  ** [PRAGMA] proc
9a40: 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73  essing continues
9a50: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
9a60: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
9a70: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
9a80: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
9a90: 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70  _OK], then the p
9aa0: 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68  arser assumes th
9ab0: 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61  at the.** VFS ha
9ac0: 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52  s handled the PR
9ad0: 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20  AGMA itself and 
9ae0: 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72  the parser gener
9af0: 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20  ates a no-op.** 
9b00: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
9b10: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51  nt.  ^If the [SQ
9b20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
9b30: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
9b40: 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72  returns.** any r
9b50: 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72  esult code other
9b60: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
9b70: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  ] or [SQLITE_NOT
9b80: 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61  FOUND], that mea
9b90: 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56  ns.** that the V
9ba0: 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61  FS encountered a
9bb0: 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61  n error while ha
9bc0: 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47  ndling the [PRAG
9bd0: 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63  MA] and the.** c
9be0: 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68  ompilation of th
9bf0: 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77  e PRAGMA fails w
9c00: 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
9c10: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9c20: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
9c30: 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73  e control occurs
9c40: 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   at the beginnin
9c50: 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74  g of pragma stat
9c60: 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61  ement analysis a
9c70: 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61  nd so.** it is a
9c80: 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20  ble to override 
9c90: 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41  built-in [PRAGMA
9ca0: 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
9cb0: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </ul>.*/.#defin
9cc0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
9cd0: 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20  OCKSTATE        
9ce0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
9cf0: 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b   SQLITE_GET_LOCK
9d00: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20  PROXYFILE       
9d10: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
9d20: 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50  SQLITE_SET_LOCKP
9d30: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20  ROXYFILE        
9d40: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
9d50: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f  QLITE_LAST_ERRNO
9d60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
9d70: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
9d80: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
9d90: 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  HINT            
9da0: 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
9db0: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
9dc0: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
9dd0: 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
9de0: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
9df0: 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20  INTER           
9e00: 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
9e10: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
9e20: 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20  TTED            
9e30: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
9e40: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
9e50: 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39  RETRY          9
9e60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9e70: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
9e80: 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  L            10.
9e90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
9ea0: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20  CNTL_OVERWRITE  
9eb0: 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23              11.#
9ec0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
9ed0: 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20  NTL_VFSNAME     
9ee0: 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64             12.#d
9ef0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
9f00: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
9f10: 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65  RWRITE    13.#de
9f20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
9f30: 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  L_PRAGMA        
9f40: 20 20 20 20 20 20 20 20 20 31 34 0a 0a 2f 2a 0a           14../*.
9f50: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
9f60: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
9f70: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
9f80: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
9f90: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
9fa0: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
9fb0: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
9fc0: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
9fd0: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
9fe0: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
9ff0: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
a000: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
a010: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
a020: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
a030: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
a040: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
a050: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
a060: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
a070: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
a080: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
a090: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
a0a0: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
a0b0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
a0c0: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
a0d0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
a0e0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
a0f0: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
a100: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
a110: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
a120: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
a130: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
a140: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
a150: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
a160: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
a170: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
a180: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
a190: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
a1a0: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
a1b0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
a1c0: 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b  ".  See.** the [
a1d0: 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65  VFS | VFS docume
a1e0: 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72  ntation] for fur
a1f0: 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ther information
a200: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ..**.** The valu
a210: 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f  e of the iVersio
a220: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69  n field is initi
a230: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62  ally 1 but may b
a240: 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66  e larger in.** f
a250: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
a260: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74  f SQLite.  Addit
a270: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79  ional fields may
a280: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
a290: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77  this.** object w
a2a0: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e  hen the iVersion
a2b0: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61   value is increa
a2c0: 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  sed.  Note that 
a2d0: 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  the structure.**
a2e0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
a2f0: 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67  vfs object chang
a300: 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61  es in the transa
a310: 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ction between.**
a320: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
a330: 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20  3.5.9 and 3.6.0 
a340: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72  and yet the iVer
a350: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e  sion field was n
a360: 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a  ot.** modified..
a370: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
a380: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
a390: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
a3a0: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
a3b0: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
a3c0: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
a3d0: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
a3e0: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
a3f0: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
a400: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
a410: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
a420: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
a430: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
a440: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
a450: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
a460: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
a470: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
a480: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
a490: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
a4a0: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
a4b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
a4c0: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
a4d0: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
a4e0: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
a4f0: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
a500: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
a510: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
a520: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
a530: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
a540: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
a550: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
a560: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
a570: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
a580: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
a590: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
a5a0: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
a5b0: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
a5c0: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
a5d0: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
a5e0: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
a5f0: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
a600: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
a610: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
a620: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
a630: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
a640: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
a650: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
a660: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
a670: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
a680: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
a690: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
a6a0: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
a6b0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
a6c0: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
a6d0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
a6e0: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
a6f0: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
a700: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
a710: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
a720: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
a730: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53  fs.xOpen]].** ^S
a740: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
a750: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
a760: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
a770: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
a780: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
a790: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
a7a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
a7b0: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69  ullPathname() wi
a7c0: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73  th an optional s
a7d0: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20  uffix added..** 
a7e0: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20  ^If a suffix is 
a7f0: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69  added to the zFi
a800: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
a810: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  , it will.** con
a820: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65  sist of a single
a830: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66   "-" character f
a840: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f  ollowed by no mo
a850: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c  re than.** 11 al
a860: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f  phanumeric and/o
a870: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73  r "-" characters
a880: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72  ..** ^SQLite fur
a890: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
a8a0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
a8b0: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
a8c0: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
a8d0: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
a8e0: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
a8f0: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
a900: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
a910: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
a920: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
a930: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
a940: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
a950: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
a960: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
a970: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
a980: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
a990: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
a9a0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69  meter to xOpen i
a9b0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
a9c0: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
a9d0: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
a9e0: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
a9f0: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
aa00: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a   ^Whenever the .
aa10: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
aa20: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
aa30: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
aa40: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
aa50: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
aa60: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
aa70: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
aa80: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
aa90: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
aaa0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
aab0: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
aac0: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
aad0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
aae0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
aaf0: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
ab00: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
ab10: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
ab20: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
ab30: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
ab40: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
ab50: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
ab60: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
ab70: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
ab80: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
ab90: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
aba0: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
abb0: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
abc0: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
abd0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
abe0: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
abf0: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
ac00: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
ac10: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c  ** ^(SQLite will
ac20: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
ac30: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
ac40: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
ac50: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
ac60: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
ac70: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
ac80: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
ac90: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
aca0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
acb0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
acc0: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
acd0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
ace0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
acf0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ad00: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
ad10: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
ad20: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
ad30: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
ad40: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
ad50: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
ad60: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
ad70: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
ad80: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ad90: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f  _OPEN_WAL].** </
ada0: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
adb0: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
adc0: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
add0: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
ade0: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
adf0: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
ae00: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
ae10: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
ae20: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
ae30: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
ae40: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
ae50: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
ae60: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
ae70: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
ae80: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
ae90: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
aea0: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
aeb0: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
aec0: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
aed0: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
aee0: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
aef0: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
af00: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
af10: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
af20: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
af30: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
af40: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
af50: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
af60: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
af70: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
af80: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
af90: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
afa0: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
afb0: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
afc0: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
afd0: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
afe0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
aff0: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
b000: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
b010: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
b020: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
b030: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
b040: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
b050: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
b060: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b070: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
b080: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
b090: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
b0a0: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
b0b0: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
b0c0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
b0d0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
b0e0: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
b0f0: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61   for TEMP databa
b100: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f  ses and their jo
b110: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e  urnals, transien
b120: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20  t.** databases, 
b130: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  and subjournals.
b140: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
b150: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
b160: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
b170: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
b180: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
b190: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
b1a0: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
b1b0: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
b1c0: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
b1d0: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
b1e0: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
b1f0: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
b200: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
b210: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
b220: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
b230: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
b240: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
b250: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
b260: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
b270: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
b280: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
b290: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
b2a0: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
b2b0: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
b2c0: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
b2d0: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
b2e0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
b2f0: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
b300: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
b310: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
b320: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73  *.** ^At least s
b330: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
b340: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
b350: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
b360: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
b370: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
b380: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
b390: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
b3a0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
b3b0: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
b3c0: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
b3d0: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
b3e0: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
b3f0: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
b400: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
b410: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
b420: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
b430: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
b440: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
b450: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
b460: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
b470: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
b480: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
b490: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
b4a0: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
b4b0: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
b4c0: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
b4d0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
b4e0: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
b4f0: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
b500: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
b510: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
b520: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
b530: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
b540: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
b550: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
b560: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a  _vfs.xAccess]].*
b570: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67  * ^The flags arg
b580: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
b590: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
b5a0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
b5b0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
b5c0: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
b5d0: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
b5e0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
b5f0: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
b600: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
b610: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
b620: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
b630: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
b640: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
b650: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
b660: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
b670: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
b680: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
b690: 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ry..**.** ^SQLit
b6a0: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
b6b0: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
b6c0: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
b6d0: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
b6e0: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
b6f0: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20  lPathname.  The 
b700: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68  exact size of th
b710: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
b720: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65  ** is also passe
b730: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72  d as a parameter
b740: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64   to both  method
b750: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  s. If the output
b760: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f   buffer.** is no
b770: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
b780: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
b790: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  ] should be retu
b7a0: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73  rned. Since this
b7b0: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61   is.** handled a
b7c0: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
b7d0: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69  by SQLite, vfs i
b7e0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
b7f0: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a  hould endeavor.*
b800: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  * to prevent thi
b810: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50  s by setting mxP
b820: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
b830: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
b840: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
b850: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
b860: 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65  xSleep(), xCurre
b870: 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43  ntTime(), and xC
b880: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
b890: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
b8a0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
b8b0: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
b8c0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
b8d0: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
b8e0: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
b8f0: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
b900: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
b910: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
b920: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
b930: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
b940: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
b950: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
b960: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
b970: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
b980: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
b990: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
b9a0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
b9b0: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
b9c0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
b9d0: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
b9e0: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
b9f0: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
ba00: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
ba10: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
ba20: 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78  s given.  ^The x
ba30: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
ba40: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
ba50: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
ba60: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
ba70: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
ba80: 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69  e as.** a floati
ba90: 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a  ng point value..
baa0: 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  ** ^The xCurrent
bab0: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
bac0: 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61  od returns, as a
bad0: 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a  n integer, the J
bae0: 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d  ulian.** Day Num
baf0: 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62  ber multiplied b
bb00: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20  y 86400000 (the 
bb10: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
bb20: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20  econds in .** a 
bb30: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a  24-hour day).  .
bb40: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
bb50: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74  use the xCurrent
bb60: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
bb70: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75  od to get the cu
bb80: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e  rrent.** date an
bb90: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d  d time if that m
bba0: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62  ethod is availab
bbb0: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20  le (if iVersion 
bbc0: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61  is 2 or .** grea
bbd0: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63  ter and the func
bbe0: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
bbf0: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69  not NULL) and wi
bc00: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20  ll fall back.** 
bc10: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  to xCurrentTime(
bc20: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d  ) if xCurrentTim
bc30: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76  eInt64() is unav
bc40: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ailable..**.** ^
bc50: 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61  The xSetSystemCa
bc60: 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d  ll(), xGetSystem
bc70: 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73  Call(), and xNes
bc80: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e  tSystemCall() in
bc90: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20  terfaces.** are 
bca0: 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20  not used by the 
bcb0: 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68  SQLite core.  Th
bcc0: 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74  ese optional int
bcd0: 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
bce0: 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20  ided.** by some 
bcf0: 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74  VFSes to facilit
bd00: 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74  ate testing of t
bd10: 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20  he VFS code. By 
bd20: 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73  overriding .** s
bd30: 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68  ystem calls with
bd40: 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72   functions under
bd50: 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20   its control, a 
bd60: 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e  test program can
bd70: 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75  .** simulate fau
bd80: 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f  lts and error co
bd90: 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f  nditions that wo
bda0: 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65  uld otherwise be
bdb0: 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72   difficult.** or
bdc0: 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69   impossible to i
bdd0: 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20  nduce.  The set 
bde0: 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  of system calls 
bdf0: 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
be00: 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73  ridden.** varies
be10: 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f   from one VFS to
be20: 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72   another, and fr
be30: 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f  om one version o
be40: 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74  f the same VFS t
be50: 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20  o the.** next.  
be60: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
be70: 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65  t use these inte
be80: 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70  rfaces must be p
be90: 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a  repared for any.
bea0: 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65  ** or all of the
beb0: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f  se interfaces to
bec0: 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20   be NULL or for 
bed0: 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74  their behavior t
bee0: 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d  o change.** from
bef0: 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20   one release to 
bf00: 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  the next.  Appli
bf10: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74  cations must not
bf20: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65   attempt to acce
bf30: 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65  ss.** any of the
bf40: 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68  se methods if th
bf50: 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68  e iVersion of th
bf60: 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68  e VFS is less th
bf70: 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  an 3..*/.typedef
bf80: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
bf90: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
bfa0: 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
bfb0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
bfc0: 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75  ptr)(void);.stru
bfd0: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
bfe0: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
bff0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
c000: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
c010: 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74   number (current
c020: 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73  ly 3) */.  int s
c030: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
c040: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
c050: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
c060: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
c070: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
c080: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
c090: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
c0a0: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
c0b0: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
c0c0: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
c0d0: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
c0e0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
c0f0: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
c100: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
c110: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
c120: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
c130: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
c140: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
c150: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
c160: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
c170: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
c180: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
c190: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
c1a0: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
c1b0: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
c1c0: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
c1d0: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
c1e0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
c1f0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
c200: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
c210: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
c220: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
c230: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
c240: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
c250: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
c260: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
c270: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
c280: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
c290: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
c2a0: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
c2b0: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
c2c0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
c2d0: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
c2e0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
c2f0: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
c300: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
c310: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
c320: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
c330: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
c340: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
c350: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
c360: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
c370: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
c380: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
c390: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
c3a0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
c3b0: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
c3c0: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
c3d0: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
c3e0: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
c3f0: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
c400: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
c410: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
c420: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
c430: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
c440: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
c450: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20  char *);.  /*.  
c460: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
c470: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
c480: 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c  ion 1 of the sql
c490: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20  ite_vfs object. 
c4a0: 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   ** definition. 
c4b0: 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c   Those that foll
c4c0: 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20  ow are added in 
c4d0: 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74  version 2 or lat
c4e0: 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  er.  */.  int (*
c4f0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
c500: 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  4)(sqlite3_vfs*,
c510: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29   sqlite3_int64*)
c520: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
c530: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
c540: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
c550: 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c  and 2 of the sql
c560: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
c570: 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77    ** Those below
c580: 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e   are for version
c590: 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a   3 and greater..
c5a0: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65    */.  int (*xSe
c5b0: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
c5c0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
c5d0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
c5e0: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
c5f0: 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79  r);.  sqlite3_sy
c600: 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74  scall_ptr (*xGet
c610: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
c620: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
c630: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
c640: 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e  const char *(*xN
c650: 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  extSystemCall)(s
c660: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
c670: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
c680: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
c690: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
c6a0: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74   in versions 1 t
c6b0: 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20  hrough 3 of the 
c6c0: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
c6d0: 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
c6e0: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
c6f0: 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72  ed in figure ver
c700: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
c710: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
c720: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
c730: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
c740: 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
c750: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
c760: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
c770: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
c780: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
c790: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
c7a0: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
c7b0: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
c7c0: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
c7d0: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
c7e0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
c7f0: 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
c800: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
c810: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
c820: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
c830: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
c840: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
c850: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
c860: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
c870: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
c880: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
c890: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
c8a0: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
c8b0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
c8c0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
c8d0: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
c8e0: 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
c8f0: 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
c900: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
c910: 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
c920: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
c930: 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
c940: 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
c950: 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
c960: 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
c970: 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
c980: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
c990: 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
c9a0: 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
c9b0: 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
c9c0: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
c9d0: 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
c9e0: 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
c9f0: 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
ca00: 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
ca10: 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
ca20: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
ca30: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
ca40: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
ca50: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
ca60: 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
ca70: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
ca80: 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
ca90: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
caa0: 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
cab0: 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
cac0: 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
cad0: 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
cae0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
caf0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
cb00: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
cb10: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
cb20: 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
cb30: 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
cb40: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
cb50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
cb60: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
cb70: 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
cb80: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
cb90: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
cba0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
cbb0: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
cbc0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
cbd0: 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
cbe0: 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
cbf0: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
cc00: 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
cc10: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
cc20: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
cc30: 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
cc40: 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
cc50: 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
cc60: 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
cc70: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
cc80: 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
cc90: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
cca0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
ccb0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
ccc0: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
ccd0: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
cce0: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
ccf0: 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
cd00: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
cd10: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
cd20: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
cd30: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
cd40: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
cd50: 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
cd60: 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
cd70: 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
cd80: 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
cd90: 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
cda0: 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
cdb0: 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f   given no the co
cdc0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
cdd0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
cde0: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
cdf0: 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
ce00: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
ce10: 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
ce20: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
ce30: 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
ce40: 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
ce50: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
ce60: 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
ce70: 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
ce80: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
ce90: 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
cea0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
ceb0: 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
cec0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
ced0: 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
cee0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
cef0: 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
cf00: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
cf10: 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
cf20: 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
cf30: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
cf40: 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
cf50: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
cf60: 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
cf70: 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
cf80: 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
cf90: 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
cfa0: 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
cfb0: 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
cfc0: 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
cfd0: 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
cfe0: 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
cff0: 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
d000: 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
d010: 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
d020: 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
d030: 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
d040: 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
d050: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
d060: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
d070: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
d080: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
d090: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
d0a0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
d0b0: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
d0c0: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
d0d0: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
d0e0: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
d0f0: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
d100: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
d110: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
d120: 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
d130: 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
d140: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
d150: 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
d160: 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
d170: 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
d180: 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
d190: 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
d1a0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
d1b0: 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
d1c0: 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
d1d0: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
d1e0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
d1f0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
d200: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
d210: 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
d220: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
d230: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d240: 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
d250: 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
d260: 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
d270: 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
d280: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
d290: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
d2a0: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
d2b0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
d2c0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
d2d0: 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
d2e0: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
d2f0: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
d300: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
d310: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
d320: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
d330: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
d340: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
d350: 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
d360: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
d370: 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
d380: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
d390: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
d3a0: 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
d3b0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
d3c0: 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
d3d0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d3e0: 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
d3f0: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
d400: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
d410: 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
d420: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
d430: 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
d440: 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
d450: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
d460: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
d470: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
d480: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
d490: 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
d4a0: 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
d4b0: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
d4c0: 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
d4d0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
d4e0: 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
d4f0: 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
d500: 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
d510: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
d520: 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
d530: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
d540: 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
d550: 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
d560: 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
d570: 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
d580: 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
d590: 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
d5a0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
d5b0: 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
d5c0: 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
d5d0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
d5e0: 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
d5f0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
d600: 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
d610: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
d620: 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
d630: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
d640: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
d650: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d660: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
d670: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
d680: 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
d690: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
d6a0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
d6b0: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
d6c0: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
d6d0: 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
d6e0: 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
d6f0: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
d700: 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
d710: 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
d720: 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
d730: 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
d740: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
d750: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
d760: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
d770: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
d780: 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
d790: 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
d7a0: 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
d7b0: 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
d7c0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
d7d0: 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
d7e0: 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
d7f0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
d800: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
d810: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
d820: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
d830: 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
d840: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
d850: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
d860: 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
d870: 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
d880: 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
d890: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
d8a0: 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
d8b0: 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
d8c0: 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
d8d0: 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
d8e0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
d8f0: 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
d900: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
d910: 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
d920: 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
d930: 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
d940: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
d950: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
d960: 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
d970: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
d980: 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
d990: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
d9a0: 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
d9b0: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
d9c0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
d9d0: 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
d9e0: 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
d9f0: 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
da00: 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
da10: 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
da20: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
da30: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
da40: 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
da50: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
da60: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
da70: 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
da80: 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
da90: 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
daa0: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
dab0: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
dac0: 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
dad0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
dae0: 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
daf0: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
db00: 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
db10: 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
db20: 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
db30: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
db40: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
db50: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
db60: 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
db70: 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
db80: 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
db90: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
dba0: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
dbb0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
dbc0: 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
dbd0: 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
dbe0: 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
dbf0: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
dc00: 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
dc10: 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
dc20: 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
dc30: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
dc40: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
dc50: 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
dc60: 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
dc70: 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
dc80: 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
dc90: 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
dca0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
dcb0: 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
dcc0: 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
dcd0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
dce0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
dcf0: 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
dd00: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
dd10: 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
dd20: 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
dd30: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
dd40: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
dd50: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
dd60: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
dd70: 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
dd80: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
dd90: 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
dda0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
ddb0: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
ddc0: 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
ddd0: 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
dde0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
ddf0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
de00: 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
de10: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
de20: 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
de30: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
de40: 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
de50: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
de60: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
de70: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
de80: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
de90: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
dea0: 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
deb0: 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
dec0: 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
ded0: 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
dee0: 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
def0: 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
df00: 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
df10: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
df20: 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
df30: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
df40: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
df50: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
df60: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
df70: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
df80: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
df90: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
dfa0: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
dfb0: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
dfc0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
dfd0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
dfe0: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
dff0: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
e000: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
e010: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
e020: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
e030: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
e040: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
e050: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
e060: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
e070: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
e080: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
e090: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
e0a0: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
e0b0: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
e0c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
e0d0: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
e0e0: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
e0f0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
e100: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
e110: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
e120: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
e130: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
e140: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
e150: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
e160: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
e170: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
e180: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
e190: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
e1a0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
e1b0: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
e1c0: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
e1d0: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
e1e0: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
e1f0: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
e200: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
e210: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
e220: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
e230: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
e240: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  needs..**.** The
e250: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
e260: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
e270: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  ot threadsafe.  
e280: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
e290: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  ** must insure t
e2a0: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
e2b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
e2c0: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
e2d0: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
e2e0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
e2f0: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
e300: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20  .  Furthermore, 
e310: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e320: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
e330: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
e340: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
e350: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
e360: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
e370: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
e380: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
e390: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
e3a0: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
e3b0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
e3c0: 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
e3d0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
e3e0: 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
e3f0: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
e400: 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
e410: 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
e420: 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
e430: 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
e440: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e450: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
e460: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
e470: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
e480: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
e490: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
e4a0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
e4b0: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
e4c0: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
e4d0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
e4e0: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f  n integer.** [co
e4f0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
e500: 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69  on] that determi
e510: 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70  nes.** what prop
e520: 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69  erty of SQLite i
e530: 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72  s to be configur
e540: 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  ed.  Subsequent 
e550: 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72  arguments.** var
e560: 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
e570: 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  he [configuratio
e580: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
e590: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
e5a0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
e5b0: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
e5c0: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
e5d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
e5e0: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
e5f0: 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
e600: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
e610: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
e620: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
e630: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
e640: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
e650: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
e660: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
e670: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  .int sqlite3_con
e680: 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a  fig(int, ...);..
e690: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
e6a0: 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61  Configure databa
e6b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
e6c0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
e6d0: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
e6e0: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
e6f0: 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61  o make configura
e700: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
e710: 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  to a [database c
e720: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
e730: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69   interface is si
e740: 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  milar to.** [sql
e750: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65  ite3_config()] e
e760: 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63  xcept that the c
e770: 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20  hanges apply to 
e780: 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74  a single.** [dat
e790: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e7a0: 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20  ] (specified in 
e7b0: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
e7c0: 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  nt)..**.** The s
e7d0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
e7e0: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
e7f0: 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73  fig(D,V,...)  is
e800: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
e810: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
e820: 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  DE | configurati
e830: 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e  on verb] - an in
e840: 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74  teger code .** t
e850: 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68  hat indicates wh
e860: 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  at aspect of the
e870: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
e880: 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
e890: 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53  configured..** S
e8a0: 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
e8b0: 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69  nts vary dependi
e8c0: 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67  ng on the config
e8d0: 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a  uration verb..**
e8e0: 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71  .** ^Calls to sq
e8f0: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
e900: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
e910: 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  OK if and only i
e920: 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73  f.** the call is
e930: 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63   considered succ
e940: 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  essful..*/.int s
e950: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
e960: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
e970: 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  p, ...);../*.** 
e980: 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
e990: 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74   Allocation Rout
e9a0: 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ines.**.** An in
e9b0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
e9c0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
e9d0: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
e9e0: 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e  een SQLite.** an
e9f0: 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  d low-level memo
ea00: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
ea10: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
ea20: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  is object is use
ea30: 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c  d in only one pl
ea40: 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74  ace in the SQLit
ea50: 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
ea60: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
ea70: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
ea80: 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61   object is the a
ea90: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73  rgument to.** [s
eaa0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
eab0: 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67   when the config
eac0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
ead0: 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  s.** [SQLITE_CON
eae0: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b  FIG_MALLOC] or [
eaf0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
eb00: 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42  TMALLOC].  .** B
eb10: 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e  y creating an in
eb20: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
eb30: 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73  bject.** and pas
eb40: 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
eb50: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
eb60: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
eb70: 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f  C]).** during co
eb80: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20  nfiguration, an 
eb90: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20  application can 
eba0: 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
ebb0: 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
ebc0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
ebd0: 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65  ystem for SQLite
ebe0: 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20   to use for all 
ebf0: 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69  of its.** dynami
ec00: 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a  c memory needs..
ec10: 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
ec20: 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74  SQLite comes wit
ec30: 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74  h several [built
ec40: 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
ec50: 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61  ators].** that a
ec60: 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65  re perfectly ade
ec70: 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76  quate for the ov
ec80: 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72  erwhelming major
ec90: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
eca0: 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ons.** and that 
ecb0: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f  this object is o
ecc0: 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20  nly useful to a 
ecd0: 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66  tiny minority of
ece0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
ecf0: 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65   with specialize
ed00: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
ed10: 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73  ion requirements
ed20: 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  .  This object i
ed30: 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64  s.** also used d
ed40: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66  uring testing of
ed50: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
ed60: 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61   to specify an a
ed70: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
ed80: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74  mory allocator t
ed90: 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65  hat simulates me
eda0: 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f  mory out-of-memo
edb0: 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e  ry conditions in
edc0: 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72  .** order to ver
edd0: 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20  ify that SQLite 
ede0: 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75  recovers gracefu
edf0: 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a  lly from such.**
ee00: 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a   conditions..**.
ee10: 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20  ** The xMalloc, 
ee20: 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46  xRealloc, and xF
ee30: 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74  ree methods must
ee40: 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a   work like the.*
ee50: 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c  * malloc(), real
ee60: 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
ee70: 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20   functions from 
ee80: 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
ee90: 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  ibrary..** ^SQLi
eea0: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
eeb0: 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  at the second ar
eec0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65  gument to.** xRe
eed0: 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20  alloc is always 
eee0: 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  a value returned
eef0: 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c   by a prior call
ef00: 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a   to xRoundup..**
ef10: 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64  .** xSize should
ef20: 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f   return the allo
ef30: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20  cated size of a 
ef40: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
ef50: 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  n.** previously 
ef60: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d  obtained from xM
ef70: 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f  alloc or xReallo
ef80: 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65  c.  The allocate
ef90: 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77  d size.** is alw
efa0: 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20  ays at least as 
efb0: 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65  big as the reque
efc0: 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61  sted size but ma
efd0: 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a  y be larger..**.
efe0: 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20  ** The xRoundup 
eff0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77  method returns w
f000: 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65  hat would be the
f010: 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
f020: 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61  of.** a memory a
f030: 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20  llocation given 
f040: 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71  a particular req
f050: 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f  uested size.  Mo
f060: 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  st memory.** all
f070: 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
f080: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
f090: 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20  ons at least to 
f0a0: 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c  the next multipl
f0b0: 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65  e.** of 8.  Some
f0c0: 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
f0d0: 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72  d up to a larger
f0e0: 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20   multiple or to 
f0f0: 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a  a power of 2..**
f100: 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c   Every memory al
f110: 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74  location request
f120: 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75   coming in throu
f130: 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  gh [sqlite3_mall
f140: 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  oc()].** or [sql
f150: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
f160: 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75  first calls xRou
f170: 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64  ndup.  If xRound
f180: 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a  up returns 0, .*
f190: 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68  * that causes th
f1a0: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
f1b0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
f1c0: 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a  n to fail..**.**
f1d0: 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   The xInit metho
f1e0: 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  d initializes th
f1f0: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
f200: 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c  or.  (For exampl
f210: 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61  e,.** it might a
f220: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75  llocate any requ
f230: 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69  ire mutexes or i
f240: 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e  nitialize intern
f250: 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63  al data.** struc
f260: 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75  tures.  The xShu
f270: 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
f280: 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63  invoked (indirec
f290: 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  tly) by.** [sqli
f2a0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
f2b0: 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c  and should deall
f2c0: 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72  ocate any resour
f2d0: 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20  ces acquired.** 
f2e0: 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70  by xInit.  The p
f2f0: 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20  AppData pointer 
f300: 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f  is used as the o
f310: 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
f320: 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53  .** xInit and xS
f330: 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53  hutdown..**.** S
f340: 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20  QLite holds the 
f350: 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
f360: 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74  ATIC_MASTER] mut
f370: 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b  ex when it invok
f380: 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20  es.** the xInit 
f390: 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78  method, so the x
f3a0: 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64  Init method need
f3b0: 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61   not be threadsa
f3c0: 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75  fe.  The.** xShu
f3d0: 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
f3e0: 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d  only called from
f3f0: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
f400: 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73  wn()] so it does
f410: 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  .** not need to 
f420: 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69  be threadsafe ei
f430: 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f  ther.  For all o
f440: 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51  ther methods, SQ
f450: 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68  Lite.** holds th
f460: 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
f470: 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65  STATIC_MEM] mute
f480: 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  x as long as the
f490: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
f4a0: 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f  IG_MEMSTATUS] co
f4b0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
f4c0: 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20  on is turned on 
f4d0: 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20  (which.** it is 
f4e0: 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20  by default) and 
f4f0: 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61  so the methods a
f500: 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
f510: 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20   serialized..** 
f520: 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c  However, if [SQL
f530: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
f540: 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65  ATUS] is disable
f550: 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65  d, then the othe
f560: 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73  r.** methods mus
f570: 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  t be threadsafe 
f580: 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65  or else make the
f590: 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65  ir own arrangeme
f5a0: 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61  nts for.** seria
f5b0: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  lization..**.** 
f5c0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
f5d0: 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29  r invoke xInit()
f5e0: 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20   more than once 
f5f0: 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72  without an inter
f600: 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74  vening.** call t
f610: 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  o xShutdown()..*
f620: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
f630: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
f640: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d  hods sqlite3_mem
f650: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
f660: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
f670: 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28  hods {.  void *(
f680: 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20  *xMalloc)(int); 
f690: 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72          /* Memor
f6a0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e  y allocation fun
f6b0: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
f6c0: 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b  (*xFree)(void*);
f6d0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65            /* Fre
f6e0: 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  e a prior alloca
f6f0: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
f700: 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64  (*xRealloc)(void
f710: 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69  *,int);  /* Resi
f720: 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze an allocation
f730: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a   */.  int (*xSiz
f740: 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
f750: 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74       /* Return t
f760: 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c  he size of an al
f770: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
f780: 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e  t (*xRoundup)(in
f790: 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t);          /* 
f7a0: 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74  Round up request
f7b0: 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74   size to allocat
f7c0: 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e  ion size */.  in
f7d0: 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a  t (*xInit)(void*
f7e0: 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
f7f0: 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  Initialize the m
f800: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
f810: 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75  */.  void (*xShu
f820: 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20  tdown)(void*);  
f830: 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c      /* Deinitial
f840: 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
f850: 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
f860: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
f870: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
f880: 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69  Argument to xIni
f890: 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77  t() and xShutdow
f8a0: 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  n() */.};../*.**
f8b0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
f8c0: 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
f8d0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
f8e0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
f8f0: 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion}.**.** These
f900: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
f910: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
f920: 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
f930: 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
f940: 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
f950: 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
f960: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
f970: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
f980: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
f990: 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
f9a0: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
f9b0: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
f9c0: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
f9d0: 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
f9e0: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
f9f0: 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
fa00: 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
fa10: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
fa20: 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
fa30: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
fa40: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  om [sqlite3_conf
fa50: 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
fa60: 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
fa70: 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65  all worked.  The
fa80: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
fa90: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
faa0: 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
fab0: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
fac0: 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
fad0: 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
fae0: 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
faf0: 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
fb00: 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
fb10: 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
fb20: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
fb30: 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
fb40: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
fb50: 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
fb60: 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
fb70: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
fb80: 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
fb90: 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
fba0: 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
fbb0: 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68  de] to Single-th
fbc0: 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
fbd0: 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
fbe0: 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69  es.** all mutexi
fbf0: 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69  ng and puts SQLi
fc00: 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77  te into a mode w
fc10: 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79  here it can only
fc20: 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61   be used.** by a
fc30: 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
fc40: 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
fc50: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
fc60: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
fc70: 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
fc80: 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
fc90: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
fca0: 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
fcb0: 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
fcc0: 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72   change the [thr
fcd0: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f  eading mode] fro
fce0: 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a  m its default.**
fcf0: 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65   value of Single
fd00: 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b  -thread and so [
fd10: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
fd20: 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a  ] will return .*
fd30: 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
fd40: 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
fd50: 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
fd60: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a  G_SINGLETHREAD.*
fd70: 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
fd80: 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
fd90: 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
fda0: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d  IG_MULTITHREAD]]
fdb0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
fdc0: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f  IG_MULTITHREAD</
fdd0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
fde0: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
fdf0: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
fe00: 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
fe10: 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
fe20: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
fe30: 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49  Multi-thread.  I
fe40: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
fe50: 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  t disables.** mu
fe60: 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
fe70: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
fe80: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
fe90: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
fea0: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
feb0: 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
fec0: 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
fed0: 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
fee0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
fef0: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
ff00: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
ff10: 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
ff20: 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
ff30: 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
ff40: 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
ff50: 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
ff60: 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
ff70: 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f  nvironment as lo
ff80: 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72  ng as no two thr
ff90: 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20  eads attempt to 
ffa0: 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
ffb0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
ffc0: 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d  tion] at the sam
ffd0: 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c  e time.  ^If SQL
ffe0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
fff0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
10000 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
10010 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
10020 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
10030 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
10040 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
10050 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
10060 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  Multi-thread [th
10070 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
10080 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
10090 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
100a0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
100b0 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
100c0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
100d0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
100e0 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  AD configuration
100f0 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
10100 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
10110 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d  FIG_SERIALIZED]]
10120 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
10130 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64  IG_SERIALIZED</d
10140 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
10150 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
10160 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
10170 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
10180 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
10190 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
101a0 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74  erialized. In ot
101b0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20  her words, this 
101c0 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a  option enables.*
101d0 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e  * all mutexes in
101e0 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75  cluding the recu
101f0 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73  rsive.** mutexes
10200 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
10210 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
10220 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
10230 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49  t] objects..** I
10240 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69  n this mode (whi
10250 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
10260 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  t when SQLite is
10270 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
10280 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
10290 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c  SAFE=1]) the SQL
102a0 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
102b0 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a   itself serializ
102c0 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b  e access.** to [
102d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
102e0 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
102f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
10300 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61  so that the.** a
10310 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72  pplication is fr
10320 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  ee to use the sa
10330 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
10340 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a  nection] or the.
10350 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  ** same [prepare
10360 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
10370 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
10380 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  s at the same ti
10390 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  me..** ^If SQLit
103a0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
103b0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
103c0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
103d0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
103e0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
103f0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
10400 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
10410 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65  le to set the Se
10420 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
10430 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
10440 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
10450 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
10460 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
10470 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
10480 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
10490 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f  IG_SERIALIZED co
104a0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
104b0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
104c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
104d0 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
104e0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
104f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
10500 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
10510 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
10520 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
10530 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
10540 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
10550 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
10560 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
10570 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
10580 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
10590 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
105a0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
105b0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
105c0 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
105d0 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
105e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
105f0 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
10600 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69   SQLite.)^ ^SQLi
10610 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20  te makes.** its 
10620 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
10630 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
10640 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
10650 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
10660 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65  ucture.** before
10670 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
10680 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74  nfig()] call ret
10690 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  urns.</dd>.**.**
106a0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
106b0 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  _GETMALLOC]] <dt
106c0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
106d0 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
106e0 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
106f0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
10700 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
10710 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
10720 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
10730 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
10740 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
10750 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73  ructure.  The [s
10760 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
10770 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
10780 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
10790 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
107a0 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  fined memory all
107b0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
107c0 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
107d0 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
107e0 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
107f0 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
10800 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
10810 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
10820 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  per that simulat
10830 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ions memory allo
10840 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f  cation failure o
10850 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f  r.** tracks memo
10860 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78  ry usage, for ex
10870 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ample. </dd>.**.
10880 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
10890 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c  IG_MEMSTATUS]] <
108a0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
108b0 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a  _MEMSTATUS</dt>.
108c0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
108d0 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
108e0 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
108f0 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65  pe int, interpre
10900 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f  ted as a .** boo
10910 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
10920 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
10930 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
10940 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
10950 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69  ion .** statisti
10960 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72  cs. ^(When memor
10970 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
10980 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
10990 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f  bled, the .** fo
109a0 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69  llowing SQLite i
109b0 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65  nterfaces become
109c0 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
109d0 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
109e0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
109f0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
10a00 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
10a10 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
10a20 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
10a30 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
10a40 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20  p_limit64()].** 
10a50 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
10a60 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c  status()].**   <
10a70 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
10a80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
10a90 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
10aa0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
10ab0 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
10ac0 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
10ad0 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
10ae0 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
10af0 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
10b00 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
10b10 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
10b20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
10b30 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
10b40 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
10b50 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64  FIG_SCRATCH]] <d
10b60 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10b70 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
10b80 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
10b90 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
10ba0 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
10bb0 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
10bc0 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63  an use for.** sc
10bd0 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54  ratch memory.  T
10be0 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
10bf0 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69  rguments:  A poi
10c00 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a  nter an 8-byte.*
10c10 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  * aligned memory
10c20 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69   buffer from whi
10c30 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61  ch the scratch a
10c40 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20  llocations will 
10c50 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65  be.** drawn, the
10c60 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63   size of each sc
10c70 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
10c80 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68   (sz),.** and th
10c90 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
10ca0 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f   of scratch allo
10cb0 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68  cations (N).  Th
10cc0 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  e sz.** argument
10cd0 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69   must be a multi
10ce0 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68  ple of 16..** Th
10cf0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10d00 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74   must be a point
10d10 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  er to an 8-byte 
10d20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a  aligned buffer.*
10d30 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  * of at least sz
10d40 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
10d50 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
10d60 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20  ill use no more 
10d70 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68  than two scratch
10d80 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72   buffers per thr
10d90 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68  ead.  So.** N sh
10da0 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74  ould be set to t
10db0 77 69 63 65 20 74 68 65 20 65 78 70 65 63 74 65  wice the expecte
10dc0 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  d maximum number
10dd0 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20   of threads..** 
10de0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76  ^SQLite will nev
10df0 65 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72  er require a scr
10e00 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74  atch buffer that
10e10 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a   is more than 6.
10e20 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74  ** times the dat
10e30 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e  abase page size.
10e40 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64   ^If SQLite need
10e50 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e  s needs addition
10e60 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65  al.** scratch me
10e70 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74  mory beyond what
10e80 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
10e90 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  this configurati
10ea0 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  on option, then 
10eb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
10ec0 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75  loc()] will be u
10ed0 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
10ee0 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e  e memory needed.
10ef0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
10f00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
10f10 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CACHE]] <dt>SQLI
10f20 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
10f30 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
10f40 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
10f50 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
10f60 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
10f70 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
10f80 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61  se for.** the da
10f90 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68  tabase page cach
10fa0 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75  e with the defau
10fb0 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  lt page cache im
10fc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a  plementation.  .
10fd0 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
10fe0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
10ff0 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61   be used if an a
11000 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
11010 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
11020 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
11030 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
11040 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
11050 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e  _PCACHE2 option.
11060 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68  .** There are th
11070 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
11080 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20   this option: A 
11090 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74  pointer to 8-byt
110a0 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d  e aligned.** mem
110b0 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  ory, the size of
110c0 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65   each page buffe
110d0 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20  r (sz), and the 
110e0 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
110f0 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61  (N)..** The sz a
11100 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
11110 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  e the size of th
11120 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61  e largest databa
11130 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f  se page.** (a po
11140 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65  wer of two betwe
11150 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38  en 512 and 32768
11160 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20  ) plus a little 
11170 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a  extra for each.*
11180 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20  * page header.  
11190 5e 54 68 65 20 70 61 67 65 20 68 65 61 64 65 72  ^The page header
111a0 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34   size is 20 to 4
111b0 30 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e  0 bytes dependin
111c0 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74  g on.** the host
111d0 20 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 20   architecture.  
111e0 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c  ^It is harmless,
111f0 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20   apart from the 
11200 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a  wasted memory,.*
11210 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c  * to make sz a l
11220 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e  ittle too large.
11230 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61    The first.** a
11240 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70  rgument should p
11250 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63  oint to an alloc
11260 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73  ation of at leas
11270 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
11280 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
11290 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
112a0 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20  memory provided 
112b0 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
112c0 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79  ument to satisfy
112d0 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e   its.** memory n
112e0 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72  eeds for the fir
112f0 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20  st N pages that 
11300 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65  it adds to cache
11310 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61  .  ^If additiona
11320 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  l.** page cache 
11330 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64  memory is needed
11340 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
11350 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
11360 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a   option, then.**
11370 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
11380 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
11390 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74  )] for the addit
113a0 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70  ional storage sp
113b0 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ace..** The poin
113c0 74 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  ter in the first
113d0 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a   argument must.*
113e0 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  * be aligned to 
113f0 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61  an 8-byte bounda
11400 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
11410 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
11420 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75  ite.** will be u
11430 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a  ndefined.</dd>.*
11440 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11450 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e  NFIG_HEAP]] <dt>
11460 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
11470 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  AP</dt>.** <dd> 
11480 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
11490 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
114a0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
114b0 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  at SQLite will u
114c0 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66  se.** for all of
114d0 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
114e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
114f0 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73  eeds beyond thos
11500 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f  e provided.** fo
11510 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
11520 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64  FIG_SCRATCH] and
11530 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
11540 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54  PAGECACHE]..** T
11550 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
11560 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62  rguments: An 8-b
11570 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
11580 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
11590 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
115a0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
115b0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
115c0 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
115d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
115e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
115f0 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
11600 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
11610 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
11620 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
11630 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
11640 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
11650 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
11660 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
11670 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
11680 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
11690 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
116a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
116b0 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
116c0 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
116d0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
116e0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
116f0 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
11700 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  or.** [SQLITE_EN
11710 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72  ABLE_MEMSYS5] ar
11720 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20  e defined, then 
11730 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
11740 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
11750 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
11760 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
11770 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
11780 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
11790 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
117a0 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
117b0 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
117c0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
117d0 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
117e0 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
117f0 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
11800 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
11810 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d  efined..** The m
11820 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
11830 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64  n size is capped
11840 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f   at 2**12. Reaso
11850 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20  nable values.** 
11860 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  for the minimum 
11870 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
11880 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68  are 2**5 through
11890 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   2**8.</dd>.**.*
118a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
118b0 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  G_MUTEX]] <dt>SQ
118c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
118d0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
118e0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
118f0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
11900 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
11910 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
11920 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
11930 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
11940 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
11950 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
11960 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
11970 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
11980 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
11990 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
119a0 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d  n place.** the m
119b0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
119c0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
119d0 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
119e0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
119f0 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  ** content of th
11a00 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
11a10 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
11a20 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63  ure before the c
11a30 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
11a40 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74  e3_config()] ret
11a50 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65  urns. ^If SQLite
11a60 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
11a70 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
11a80 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
11a90 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
11aa0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
11ab0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
11ac0 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
11ad0 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
11ae0 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
11af0 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
11b00 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
11b10 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11b20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
11b30 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e  CONFIG_MUTEX con
11b40 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11b50 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
11b60 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
11b70 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
11b80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
11b90 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
11ba0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
11bb0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
11bc0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
11bd0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
11be0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
11bf0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
11c00 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
11c10 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
11c20 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
11c30 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  re.  The.** [sql
11c40 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
11c50 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
11c60 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
11c70 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
11c80 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74  fined mutex rout
11c90 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
11ca0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
11cb0 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
11cc0 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
11cd0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
11ce0 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
11cf0 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74  rapper used to t
11d00 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65  rack mutex usage
11d10 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
11d20 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72  .** profiling or
11d30 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78   testing, for ex
11d40 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c  ample.   ^If SQL
11d50 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11d60 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
11d70 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
11d80 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
11d90 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
11da0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
11db0 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
11dc0 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
11dd0 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
11de0 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
11df0 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
11e00 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11e10 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
11e20 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
11e30 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
11e40 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
11e50 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
11e60 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
11e70 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
11e80 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64  G_LOOKASIDE]] <d
11e90 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11ea0 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
11eb0 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
11ec0 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
11ed0 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
11ee0 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61  termine the defa
11ef0 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ult.** memory al
11f00 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  location for the
11f10 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
11f20 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65  y allocator on e
11f30 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
11f40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
11f50 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
11f60 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
11f70 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
11f80 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
11f90 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
11fa0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
11fb0 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
11fc0 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
11fd0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e  se connection.)^
11fe0 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20    ^(This option 
11ff0 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64  sets the.** <i>d
12000 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61  efault</i> looka
12010 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b  side size. The [
12020 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
12030 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65  LOOKASIDE].** ve
12040 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  rb to [sqlite3_d
12050 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20  b_config()] can 
12060 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  be used to chang
12070 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
12080 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
12090 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63   on individual c
120a0 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f  onnections.)^ </
120b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
120c0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
120d0 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
120e0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64  ONFIG_PCACHE2</d
120f0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
12100 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
12110 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
12120 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
12130 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71  ter to.** an [sq
12140 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
12150 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
12160 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
12170 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66  ifies the interf
12180 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74  ace.** to a cust
12190 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
121a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20  plementation.)^ 
121b0 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
121c0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
121d0 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20  object and uses 
121e0 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68  it for page cach
121f0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
12200 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ions.</dd>.**.**
12210 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12220 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64  _GETPCACHE2]] <d
12230 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12240 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  GETPCACHE2</dt>.
12250 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
12260 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
12270 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
12280 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
12290 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
122a0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
122b0 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c  s2] object.  SQL
122c0 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68  ite copies of th
122d0 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67  e current.** pag
122e0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
122f0 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74  tation into that
12300 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e   object.)^ </dd>
12310 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12320 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74  CONFIG_LOG]] <dt
12330 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
12340 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OG</dt>.** <dd> 
12350 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
12360 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61  IG_LOG option ta
12370 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
12380 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: a pointer to 
12390 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  a.** function wi
123a0 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74  th a call signat
123b0 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76  ure of void(*)(v
123c0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
123d0 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61  har*), .** and a
123e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64   pointer to void
123f0 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  . ^If the functi
12400 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
12410 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a  t NULL, it is.**
12420 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c   invoked by [sql
12430 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70  ite3_log()] to p
12440 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67  rocess each logg
12450 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
12460 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
12470 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c  pointer is NULL,
12480 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
12490 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  g()] interface b
124a0 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a  ecomes a no-op..
124b0 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69  ** ^The void poi
124c0 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65  nter that is the
124d0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
124e0 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
124f0 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73  G_LOG is.** pass
12500 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
12510 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
12520 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  r to the applica
12530 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
12540 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
12550 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75  whenever that fu
12560 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
12570 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  d.  ^The second 
12580 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
12590 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
125a0 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ion is a copy of
125b0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
125c0 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72  eter to the corr
125d0 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71  esponding.** [sq
125e0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c  lite3_log()] cal
125f0 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65  l and is intende
12600 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c  d to be a [resul
12610 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  t code] or an.**
12620 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
12630 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74  t code].  ^The t
12640 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70  hird parameter p
12650 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67  assed to the log
12660 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65  ger is.** log me
12670 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d  ssage after form
12680 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69  atting via [sqli
12690 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e  te3_snprintf()].
126a0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c  .** The SQLite l
126b0 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65  ogging interface
126c0 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
126d0 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  t; the logger fu
126e0 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  nction.** suppli
126f0 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
12700 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69  ation must not i
12710 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65  nvoke any SQLite
12720 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
12730 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
12740 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  ed application, 
12750 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
12760 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
12770 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
12780 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c  be threadsafe. <
12790 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
127a0 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d  ITE_CONFIG_URI]]
127b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
127c0 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54  IG_URI.** <dd> T
127d0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
127e0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
127f0 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20  nt of type int. 
12800 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  If non-zero, the
12810 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e  n.** URI handlin
12820 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
12830 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61  abled. If the pa
12840 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c  rameter is zero,
12850 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
12860 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c  ng.** is globall
12870 79 20 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55  y disabled. If U
12880 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
12890 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c  lobally enabled,
128a0 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a   all filenames.*
128b0 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  * passed to [sql
128c0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
128d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
128e0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
128f0 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63  16()] or.** spec
12900 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66  ified as part of
12910 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e   [ATTACH] comman
12920 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  ds are interpret
12930 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61  ed as URIs, rega
12940 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65  rdless.** of whe
12950 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
12960 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
12970 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  ] flag is set wh
12980 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  en the database.
12990 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
129a0 20 6f 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69   opened. If it i
129b0 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
129c0 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61  led, filenames a
129d0 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72  re.** only inter
129e0 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69  preted as URIs i
129f0 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  f the SQLITE_OPE
12a00 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65  N_URI flag is se
12a10 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61  t when the.** da
12a20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12a30 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20  n is opened. By 
12a40 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e  default, URI han
12a50 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
12a60 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54  y.** disabled. T
12a70 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
12a80 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20   may be changed 
12a90 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74  by compiling wit
12aa0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
12ab0 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c  _USE_URI] symbol
12ac0 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
12ad0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12ae0 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54  PCACHE]] [[SQLIT
12af0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
12b00 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  HE]].** <dt>SQLI
12b10 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
12b20 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46   and SQLITE_CONF
12b30 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20  IG_GETPCACHE.** 
12b40 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f  <dd> These optio
12b50 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20  ns are obsolete 
12b60 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  and should not b
12b70 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f  e used by new co
12b80 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20  de..** They are 
12b90 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63  retained for bac
12ba0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
12bb0 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77  lity but are now
12bc0 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 6c   no-ops..** </dl
12bd0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
12be0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
12bf0 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
12c00 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
12c10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
12c20 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
12c30 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
12c40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
12c50 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
12c60 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
12c70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
12c80 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
12c90 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
12ca0 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
12cb0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12cc0 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
12cd0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
12ce0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
12cf0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
12d00 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
12d10 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  6  /* void*, int
12d20 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
12d30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
12d40 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20  FIG_PAGECACHE   
12d50 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    7  /* void*, i
12d60 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
12d70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
12d80 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
12d90 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c      8  /* void*,
12da0 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20   int nByte, int 
12db0 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  min */.#define S
12dc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
12dd0 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a  STATUS     9  /*
12de0 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66   boolean */.#def
12df0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
12e00 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31  G_MUTEX        1
12e10 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  0  /* sqlite3_mu
12e20 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
12e30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
12e40 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20  ONFIG_GETMUTEX  
12e50 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65     11  /* sqlite
12e60 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
12e70 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c   */./* previousl
12e80 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  y SQLITE_CONFIG_
12e90 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68  CHUNKALLOC 12 wh
12ea0 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65  ich is now unuse
12eb0 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53  d. */ .#define S
12ec0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
12ed0 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a  KASIDE    13  /*
12ee0 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
12ef0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
12f00 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31  G_PCACHE       1
12f10 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  4  /* no-op */.#
12f20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
12f30 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20  NFIG_GETPCACHE  
12f40 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    15  /* no-op *
12f50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
12f60 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20  _CONFIG_LOG     
12f70 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e       16  /* xFun
12f80 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66  c, void* */.#def
12f90 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
12fa0 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31  G_URI          1
12fb0 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  7  /* int */.#de
12fc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
12fd0 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20  IG_PCACHE2      
12fe0 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  18  /* sqlite3_p
12ff0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
13000 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13010 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
13020 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c  HE2   19  /* sql
13030 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
13040 6f 64 73 32 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  ods2* */../*.** 
13050 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
13060 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f  se Connection Co
13070 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
13080 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
13090 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
130a0 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
130b0 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
130c0 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
130d0 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
130e0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
130f0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
13100 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
13110 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
13120 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
13130 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
13140 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
13150 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
13160 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
13170 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
13180 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
13190 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
131a0 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
131b0 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
131c0 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
131d0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64   from [sqlite3_d
131e0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  b_config()] to m
131f0 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
13200 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
13210 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  .  ^The [sqlite3
13220 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
13230 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
13240 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
13250 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
13260 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
13270 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
13280 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13290 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
132a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
132b0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
132c0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
132d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
132e0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
132f0 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c  three additional
13300 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
13310 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a  determine the .*
13320 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  * [lookaside mem
13330 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63  ory allocator] c
13340 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
13350 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
13360 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e  onnection]..** ^
13370 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
13380 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61  nt (the third pa
13390 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
133a0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
133b0 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72   is a.** pointer
133c0 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66   to a memory buf
133d0 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c  fer to use for l
133e0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e  ookaside memory.
133f0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
13400 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68  rgument after th
13410 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
13420 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62  G_LOOKASIDE verb
13430 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20  .** may be NULL 
13440 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51  in which case SQ
13450 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61  Lite will alloca
13460 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73  te the.** lookas
13470 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c  ide buffer itsel
13480 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  f using [sqlite3
13490 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65  _malloc()]. ^The
134a0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
134b0 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
134c0 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
134d0 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20  e buffer slot.  
134e0 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
134f0 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ent is the numbe
13500 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20  r of.** slots.  
13510 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
13520 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69  buffer in the fi
13530 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
13540 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61  t be greater tha
13550 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f  n.** or equal to
13560 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20   the product of 
13570 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
13580 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20  hird arguments. 
13590 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d   The buffer.** m
135a0 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
135b0 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
135c0 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73  dary.  ^If the s
135d0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
135e0 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f  o.** SQLITE_DBCO
135f0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69  NFIG_LOOKASIDE i
13600 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65  s not a multiple
13610 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74   of 8, it is int
13620 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64  ernally.** round
13630 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e  ed down to the n
13640 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74  ext smaller mult
13650 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68  iple of 8.  ^(Th
13660 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
13670 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  ry.** configurat
13680 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61  ion for a databa
13690 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61  se connection ca
136a0 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65  n only be change
136b0 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63  d when that.** c
136c0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74  onnection is not
136d0 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67   currently using
136e0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
136f0 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77  y, or in other w
13700 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65  ords.** when the
13710 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22   "current value"
13720 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
13730 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74  [sqlite3_db_stat
13740 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f  us](D,[SQLITE_CO
13750 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c  NFIG_LOOKASIDE],
13760 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a  ...) is zero..**
13770 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
13780 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
13790 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66  side memory conf
137a0 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c  iguration when l
137b0 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f  ookaside.** memo
137c0 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61  ry is in use lea
137d0 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72  ves the configur
137e0 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20  ation unchanged 
137f0 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20  and returns .** 
13800 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e  [SQLITE_BUSY].)^
13810 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
13820 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
13830 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e  ENABLE_FKEY</dt>
13840 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
13850 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
13860 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
13870 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65  le the enforceme
13880 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67  nt of.** [foreig
13890 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74  n key constraint
138a0 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c  s].  There shoul
138b0 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
138c0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
138d0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
138e0 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
138f0 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
13900 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f   disable FK enfo
13910 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69  rcement,.** posi
13920 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46  tive to enable F
13930 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72  K enforcement or
13940 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
13950 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  ve FK enforcemen
13960 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20  t.** unchanged. 
13970 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
13980 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
13990 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
139a0 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
139b0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
139c0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
139d0 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d  ther FK enforcem
139e0 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e  ent is off or on
139f0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
13a00 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
13a10 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
13a20 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
13a30 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
13a40 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e  h case the FK en
13a50 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e  forcement settin
13a60 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
13a70 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
13a80 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
13a90 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
13aa0 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  RIGGER</dt>.** <
13ab0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
13ac0 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
13ad0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43  le or disable [C
13ae0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
13af0 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68  triggers]..** Th
13b00 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
13b10 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
13b20 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
13b30 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
13b40 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
13b50 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
13b60 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70  e triggers,.** p
13b70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
13b80 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65  e triggers or ne
13b90 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
13ba0 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68  the setting unch
13bb0 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65  anged..** The se
13bc0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
13bd0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
13be0 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
13bf0 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
13c00 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
13c10 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72  icate whether tr
13c20 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62  iggers are disab
13c30 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
13c40 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
13c50 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
13c60 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
13c70 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
13c80 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
13c90 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72  case the trigger
13ca0 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
13cb0 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
13cc0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
13cd0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
13ce0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
13cf0 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31  ASIDE       1001
13d00 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69    /* void* int i
13d10 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
13d20 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
13d30 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30  ABLE_FKEY     10
13d40 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  02  /* int int* 
13d50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13d60 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
13d70 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20  E_TRIGGER  1003 
13d80 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
13d90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13da0 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
13db0 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73  ble Extended Res
13dc0 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ult Codes.**.** 
13dd0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
13de0 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
13df0 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61  es() routine ena
13e00 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
13e10 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65   the.** [extende
13e20 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
13e30 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74  feature of SQLit
13e40 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64  e. ^The extended
13e50 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73   result.** codes
13e60 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
13e70 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73   default for his
13e80 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62  torical compatib
13e90 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ility..*/.int sq
13ea0 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
13eb0 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69  esult_codes(sqli
13ec0 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29  te3*, int onoff)
13ed0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
13ee0 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  F: Last Insert R
13ef0 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  owid.**.** ^Each
13f00 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c   entry in an SQL
13f10 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  ite table has a 
13f20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
13f30 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
13f40 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b  key called the [
13f50 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d  ROWID | "rowid"]
13f60 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20  . ^The rowid is 
13f70 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
13f80 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
13f90 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
13fa0 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
13fb0 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
13fc0 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
13fd0 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
13fe0 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
13ff0 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
14000 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20  mns. ^If.** the 
14010 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
14020 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45  mn of type [INTE
14030 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
14040 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
14050 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
14060 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f  alias for the ro
14070 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  wid..**.** ^This
14080 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
14090 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
140a0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a  the most recent.
140b0 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
140c0 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20  NSERT] into the 
140d0 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68  database from th
140e0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
140f0 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  ection].** in th
14100 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
14110 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c 69 74 65  .  ^As of SQLite
14120 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20   version 3.7.7, 
14130 74 68 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  this routines.**
14140 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61 73   records the las
14150 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 20 6f  t insert rowid o
14160 66 20 62 6f 74 68 20 6f 72 64 69 6e 61 72 79 20  f both ordinary 
14170 74 61 62 6c 65 73 20 61 6e 64 20 5b 76 69 72 74  tables and [virt
14180 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20  ual tables]..** 
14190 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75  ^If no successfu
141a0 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68  l [INSERT]s.** h
141b0 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
141c0 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61  d on that databa
141d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a  se connection, z
141e0 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
141f0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b  .**.** ^(If an [
14200 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77  INSERT] occurs w
14210 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
14220 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72  or within a [vir
14230 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d  tual table].** m
14240 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73  ethod, then this
14250 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65   routine will re
14260 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  turn the [rowid]
14270 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
14280 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20  .** row as long 
14290 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  as the trigger o
142a0 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
142b0 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e  method is runnin
142c0 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74  g..** But once t
142d0 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
142e0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
142f0 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c  od ends, the val
14300 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20  ue returned .** 
14310 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
14320 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20  reverts to what 
14330 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68  it was before th
14340 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
14350 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65  tual.** table me
14360 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a  thod began.)^.**
14370 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d  .** ^An [INSERT]
14380 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20   that fails due 
14390 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  to a constraint 
143a0 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74  violation is not
143b0 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c   a.** successful
143c0 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f   [INSERT] and do
143d0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
143e0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
143f0 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   by this.** rout
14400 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45  ine.  ^Thus INSE
14410 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45  RT OR FAIL, INSE
14420 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e  RT OR IGNORE, IN
14430 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b  SERT OR ROLLBACK
14440 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20  ,.** and INSERT 
14450 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f  OR ABORT make no
14460 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
14470 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
14480 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
14490 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72  when their inser
144a0 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57  tion fails.  ^(W
144b0 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45  hen INSERT OR RE
144c0 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74  PLACE.** encount
144d0 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
144e0 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
144f0 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
14500 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
14510 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
14520 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
14530 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
14540 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
14550 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
14560 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
14570 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
14580 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
14590 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
145a0 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a  is interface.)^.
145b0 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
145c0 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
145d0 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53  routine, an [INS
145e0 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72  ERT] is consider
145f0 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63  ed to.** be succ
14600 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69  essful even if i
14610 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c  t is subsequentl
14620 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
14630 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
14640 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65  on is accessible
14650 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   to SQL statemen
14660 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c  ts via the.** [l
14670 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
14680 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
14690 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
146a0 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72  arate thread per
146b0 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53  forms a new [INS
146c0 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65  ERT] on the same
146d0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
146e0 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
146f0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
14700 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a  insert_rowid()].
14710 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ** function is r
14720 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
14730 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
14740 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c   insert [rowid],
14750 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c  .** then the val
14760 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ue returned by [
14770 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
14780 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a  ert_rowid()] is.
14790 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  ** unpredictable
147a0 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65   and might not e
147b0 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20  qual either the 
147c0 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a  old or the new.*
147d0 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  * last insert [r
147e0 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65  owid]..*/.sqlite
147f0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
14800 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
14810 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  d(sqlite3*);../*
14820 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
14830 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f  unt The Number O
14840 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
14850 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
14860 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
14870 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62   number of datab
14880 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65  ase rows that we
14890 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72  re changed.** or
148a0 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
148b0 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  eted by the most
148c0 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
148d0 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
148e0 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74  t.** on the [dat
148f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14900 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  ] specified by t
14910 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
14920 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68  er..** ^(Only ch
14930 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64  anges that are d
14940 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65  irectly specifie
14950 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54  d by the [INSERT
14960 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20  ], [UPDATE],.** 
14970 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
14980 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65  ement are counte
14990 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68  d.  Auxiliary ch
149a0 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a  anges caused by.
149b0 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b  ** triggers or [
149c0 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
149d0 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75  ons] are not cou
149e0 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a  nted.)^ Use the.
149f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  ** [sqlite3_tota
14a00 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e  l_changes()] fun
14a10 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68  ction to find th
14a20 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
14a30 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63  f changes.** inc
14a40 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63  luding changes c
14a50 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72  aused by trigger
14a60 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65  s and foreign ke
14a70 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  y actions..**.**
14a80 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76   ^Changes to a v
14a90 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d  iew that are sim
14aa0 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e  ulated by an [IN
14ab0 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
14ac0 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75  ].** are not cou
14ad0 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c  nted.  Only real
14ae0 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61   table changes a
14af0 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a  re counted..**.*
14b00 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67  * ^(A "row chang
14b10 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74  e" is a change t
14b20 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f  o a single row o
14b30 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65  f a single table
14b40 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e  .** caused by an
14b50 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c   INSERT, DELETE,
14b60 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65   or UPDATE state
14b70 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74  ment.  Rows that
14b80 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20  .** are changed 
14b90 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20  as side effects 
14ba0 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e  of [REPLACE] con
14bb0 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
14bc0 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c  on,.** rollback,
14bd0 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
14be0 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c  g, [DROP TABLE],
14bf0 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72   or by any other
14c00 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64  .** mechanisms d
14c10 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64  o not count as d
14c20 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
14c30 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72  s.)^.**.** A "tr
14c40 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69  igger context" i
14c50 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65  s a scope of exe
14c60 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69  cution that begi
14c70 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77  ns and.** ends w
14c80 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f  ith the script o
14c90 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47  f a [CREATE TRIG
14ca0 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20  GER | trigger]. 
14cb0 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61  .** Most SQL sta
14cc0 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65  tements are.** e
14cd0 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65  valuated outside
14ce0 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e   of any trigger.
14cf0 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74    This is the "t
14d00 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69  op level".** tri
14d10 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49  gger context.  I
14d20 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65  f a trigger fire
14d30 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  s from the top l
14d40 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74  evel, a.** new t
14d50 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69  rigger context i
14d60 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68  s entered for th
14d70 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68  e duration of th
14d80 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65  at one.** trigge
14d90 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20  r.  Subtriggers 
14da0 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78  create subcontex
14db0 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72  ts for their dur
14dc0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  ation..**.** ^Ca
14dd0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
14de0 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  xec()] or [sqlit
14df0 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72  e3_step()] recur
14e00 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e  sively does.** n
14e10 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20  ot create a new 
14e20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
14e30 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
14e40 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
14e50 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65  e number of dire
14e60 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69  ct row changes i
14e70 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65  n the.** most re
14e80 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
14e90 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73  ATE, or DELETE s
14ea0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
14eb0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67  the same.** trig
14ec0 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
14ed0 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63  ** ^Thus, when c
14ee0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74  alled from the t
14ef0 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66  op level, this f
14f00 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
14f10 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
14f20 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
14f30 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
14f40 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
14f50 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c  ELETE.** that al
14f60 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74  so occurred at t
14f70 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e  he top level.  ^
14f80 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79  (Within the body
14f90 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a   of a trigger,.*
14fa0 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  * the sqlite3_ch
14fb0 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63  anges() interfac
14fc0 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
14fd0 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
14fe0 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73  er of.** changes
14ff0 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
15000 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
15010 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
15020 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
15030 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
15040 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61  e body of the sa
15050 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48  me trigger..** H
15060 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62  owever, the numb
15070 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  er returned does
15080 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
15090 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62  nges.** caused b
150a0 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69  y subtriggers si
150b0 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74  nce those have t
150c0 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74  heir own context
150d0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
150e0 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
150f0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
15100 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
15110 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
15120 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
15130 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
15140 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
15150 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
15160 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
15170 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
15180 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
15190 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
151a0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
151b0 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
151c0 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
151d0 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72  urned.** is unpr
151e0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
151f0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
15200 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61  .int sqlite3_cha
15210 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
15220 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
15230 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66   Total Number Of
15240 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
15250 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
15260 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
15270 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68  number of row ch
15280 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
15290 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50  [INSERT],.** [UP
152a0 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45  DATE] or [DELETE
152b0 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e  ] statements sin
152c0 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ce the [database
152d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73   connection] was
152e0 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68   opened..** ^(Th
152f0 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64  e count returned
15300 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61   by sqlite3_tota
15310 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c  l_changes() incl
15320 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73  udes all changes
15330 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52  .** from all [CR
15340 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
15350 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73  rigger] contexts
15360 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64   and changes mad
15370 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  e by.** [foreign
15380 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48   key actions]. H
15390 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63  owever,.** the c
153a0 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
153b0 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73  clude changes us
153c0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
153d0 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
153e0 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c  aints,.** do rol
153f0 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20  lbacks or ABORT 
15400 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b  processing, or [
15410 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63  DROP TABLE] proc
15420 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20  essing.  The.** 
15430 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69  count does not i
15440 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76  nclude rows of v
15450 69 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61  iews that fire a
15460 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  n [INSTEAD OF tr
15470 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67  igger],.** thoug
15480 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44  h if the INSTEAD
15490 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65   OF trigger make
154a0 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73  s changes of its
154b0 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e   own, those chan
154c0 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e  ges .** are coun
154d0 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73  ted.)^.** ^The s
154e0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
154f0 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  nges() function 
15500 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67  counts the chang
15510 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a  es as soon as.**
15520 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
15530 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69  hat makes them i
15540 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65  s completed (whe
15550 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
15560 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73  handle.** is pas
15570 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  sed to [sqlite3_
15580 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
15590 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
155a0 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
155b0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
155c0 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
155d0 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
155e0 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
155f0 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74  a], and the [tot
15600 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c  al_changes() SQL
15610 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
15620 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
15630 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
15640 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
15650 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15660 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
15670 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
15680 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
15690 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
156a0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
156b0 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
156c0 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
156d0 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
156e0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
156f0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
15700 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
15710 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
15720 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a  ning Query.**.**
15730 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
15740 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69  causes any pendi
15750 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  ng database oper
15760 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61  ation to abort a
15770 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20  nd.** return at 
15780 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70  its earliest opp
15790 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72  ortunity. This r
157a0 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61  outine is typica
157b0 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e  lly.** called in
157c0 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75   response to a u
157d0 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20  ser action such 
157e0 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e  as pressing "Can
157f0 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d  cel".** or Ctrl-
15800 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72  C where the user
15810 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75   wants a long qu
15820 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ery operation to
15830 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61   halt.** immedia
15840 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  tely..**.** ^It 
15850 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
15860 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
15870 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
15880 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
15890 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
158a0 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
158b0 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
158c0 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
158d0 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
158e0 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
158f0 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
15900 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15910 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
15920 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
15930 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
15940 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
15950 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  eturns..**.** ^I
15960 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  f an SQL operati
15970 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c  on is very nearl
15980 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68  y finished at th
15990 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73  e time when.** s
159a0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
159b0 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  () is called, th
159c0 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20  en it might not 
159d0 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e  have an opportun
159e0 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74  ity.** to be int
159f0 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67  errupted and mig
15a00 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63  ht continue to c
15a10 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ompletion..**.**
15a20 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69   ^An SQL operati
15a30 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
15a40 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
15a50 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
15a60 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  RUPT]..** ^If th
15a70 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51  e interrupted SQ
15a80 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  L operation is a
15a90 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
15aa0 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
15ab0 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e  hat is inside an
15ac0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
15ad0 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ction, then the 
15ae0 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69  entire transacti
15af0 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f  on.** will be ro
15b00 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
15b10 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  tically..**.** ^
15b20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  The sqlite3_inte
15b30 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73  rrupt(D) call is
15b40 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c   in effect until
15b50 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72   all currently r
15b60 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
15b70 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74  atements on [dat
15b80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15b90 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  ] D complete.  ^
15ba0 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74  Any new SQL stat
15bb0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
15bc0 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
15bd0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
15be0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e  errupt() call an
15bf0 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a  d before the .**
15c00 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
15c10 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f  nts reaches zero
15c20 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64   are interrupted
15c30 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20   as if they had 
15c40 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  been.** running 
15c50 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c  prior to the sql
15c60 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
15c70 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c   call.  ^New SQL
15c80 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
15c90 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
15ca0 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e  after the runnin
15cb0 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e  g statement coun
15cc0 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  t reaches zero a
15cd0 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74  re.** not effect
15ce0 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
15cf0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a  3_interrupt()..*
15d00 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  * ^A call to sql
15d10 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
15d20 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68  ) that occurs wh
15d30 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  en there are no 
15d40 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
15d50 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e  tatements is a n
15d60 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20  o-op and has no 
15d70 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74  effect on SQL st
15d80 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
15d90 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
15da0 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
15db0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
15dc0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  returns..**.** I
15dd0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
15de0 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
15df0 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
15e00 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20  interrupt()].** 
15e10 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
15e20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20  bad things will 
15e30 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a  likely happen..*
15e40 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69  /.void sqlite3_i
15e50 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33  nterrupt(sqlite3
15e60 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
15e70 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
15e80 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
15e90 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a  nt Is Complete.*
15ea0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
15eb0 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64  nes are useful d
15ec0 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69  uring command-li
15ed0 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
15ee0 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
15ef0 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
15f00 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20  d text seems to 
15f10 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20  form a complete 
15f20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  SQL statement or
15f30 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61  .** if additiona
15f40 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65  l input is neede
15f50 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67  d before sending
15f60 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a   the text into.*
15f70 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72  * SQLite for par
15f80 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f  sing.  ^These ro
15f90 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20  utines return 1 
15fa0 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  if the input str
15fb0 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74  ing.** appears t
15fc0 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20  o be a complete 
15fd0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
15fe0 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ^A statement is 
15ff0 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20  judged to be.** 
16000 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65  complete if it e
16010 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63  nds with a semic
16020 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69  olon token and i
16030 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f  s not a prefix o
16040 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d  f a.** well-form
16050 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45  ed CREATE TRIGGE
16060 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53  R statement.  ^S
16070 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61  emicolons that a
16080 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68  re embedded with
16090 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74  in.** string lit
160a0 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20  erals or quoted 
160b0 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73  identifier names
160c0 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65   or comments are
160d0 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64   not.** independ
160e0 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79  ent tokens (they
160f0 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65   are part of the
16100 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20   token in which 
16110 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65  they are.** embe
16120 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64  dded) and thus d
16130 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61  o not count as a
16140 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69   statement termi
16150 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70  nator.  ^Whitesp
16160 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65  ace.** and comme
16170 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  nts that follow 
16180 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f  the final semico
16190 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e  lon are ignored.
161a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
161b0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20  utines return 0 
161c0 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
161d0 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20   is incomplete. 
161e0 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79   ^If a.** memory
161f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
16200 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e  s, then SQLITE_N
16210 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64  OMEM is returned
16220 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
16230 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70  outines do not p
16240 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61  arse the SQL sta
16250 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20  tements thus.** 
16260 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20  will not detect 
16270 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e  syntactically in
16280 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a  correct SQL..**.
16290 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68  ** ^(If SQLite h
162a0 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74  as not been init
162b0 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73  ialized using [s
162c0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
162d0 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74  e()] prior .** t
162e0 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74  o invoking sqlit
162f0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
16300 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69  then sqlite3_ini
16310 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
16320 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  oked.** automati
16330 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
16340 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20  _complete16().  
16350 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69  If that initiali
16360 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a  zation fails,.**
16370 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
16380 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
16390 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
163a0 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72   will be non-zer
163b0 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  o.** regardless 
163c0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
163d0 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20  t the input SQL 
163e0 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a  is complete.)^.*
163f0 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
16400 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
16410 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61  ete()] must be a
16420 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
16430 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67  .** UTF-8 string
16440 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ..**.** The inpu
16450 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
16460 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74  mplete16()] must
16470 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
16480 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
16490 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
164a0 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a   byte order..*/.
164b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
164c0 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
164d0 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  *sql);.int sqlit
164e0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
164f0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
16500 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16510 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
16520 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
16530 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
16540 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
16550 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c  utine sets a cal
16560 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74  lback function t
16570 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76  hat might be inv
16580 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a  oked whenever.**
16590 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
165a0 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61  ade to open a da
165b0 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61  tabase table tha
165c0 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  t another thread
165d0 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68  .** or process h
165e0 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a  as locked..**.**
165f0 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
16600 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20  llback is NULL, 
16610 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  then [SQLITE_BUS
16620 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
16630 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
16640 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
16650 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63  diately upon enc
16660 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f  ountering the lo
16670 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73  ck.  ^If the bus
16680 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  y callback.** is
16690 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
166a0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67  the callback mig
166b0 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
166c0 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  th two arguments
166d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
166e0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
166f0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
16700 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
16710 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
16720 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
16730 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
16740 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
16750 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73  ndler().  ^The s
16760 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
16770 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  o.** the busy ha
16780 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
16790 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
167a0 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
167b0 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
167c0 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
167d0 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67  for this locking
167e0 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
167f0 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63  .** busy callbac
16800 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65  k returns 0, the
16810 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20  n no additional 
16820 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64  attempts are mad
16830 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74  e to.** access t
16840 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
16850 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
16860 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
16870 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72  LOCKED] is retur
16880 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ned..** ^If the 
16890 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
168a0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
168b0 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a  another attempt.
168c0 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  ** is made to op
168d0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
168e0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
168f0 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74  the cycle repeat
16900 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65  s..**.** The pre
16910 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20  sence of a busy 
16920 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74  handler does not
16930 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
16940 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  it will be invok
16950 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65  ed.** when there
16960 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74   is lock content
16970 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ion. ^If SQLite 
16980 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20  determines that 
16990 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
169a0 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75  y.** handler cou
169b0 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64  ld result in a d
169c0 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c  eadlock, it will
169d0 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65   go ahead and re
169e0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
169f0 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  Y].** or [SQLITE
16a00 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20  _IOERR_BLOCKED] 
16a10 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b  instead of invok
16a20 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e  ing the busy han
16a30 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65  dler..** Conside
16a40 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65  r a scenario whe
16a50 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69  re one process i
16a60 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64  s holding a read
16a70 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74   lock that.** it
16a80 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72   is trying to pr
16a90 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72  omote to a reser
16aa0 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20  ved lock and.** 
16ab0 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  a second process
16ac0 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
16ad0 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74  served lock that
16ae0 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a   it is trying.**
16af0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
16b00 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b  n exclusive lock
16b10 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f  .  The first pro
16b20 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63  cess cannot proc
16b30 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69  eed.** because i
16b40 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
16b50 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
16b60 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
16b70 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63  s cannot.** proc
16b80 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69  eed because it i
16b90 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
16ba0 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68   first.  If both
16bb0 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e   processes.** in
16bc0 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61  voke the busy ha
16bd0 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20  ndlers, neither 
16be0 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72  will make any pr
16bf0 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f  ogress.  Therefo
16c00 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65  re,.** SQLite re
16c10 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
16c20 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  SY] for the firs
16c30 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e  t process, hopin
16c40 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77  g that this.** w
16c50 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66  ill induce the f
16c60 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20  irst process to 
16c70 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64  release its read
16c80 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a   lock and allow.
16c90 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  ** the second pr
16ca0 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64  ocess to proceed
16cb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
16cc0 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61  ault busy callba
16cd0 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ck is NULL..**.*
16ce0 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42  * ^The [SQLITE_B
16cf0 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f  USY] error is co
16d00 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49  nverted to [SQLI
16d10 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
16d20 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  ].** when SQLite
16d30 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c   is in the middl
16d40 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61  e of a large tra
16d50 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61  nsaction where a
16d60 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65  ll the.** change
16d70 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69  s will not fit i
16d80 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72  nto the in-memor
16d90 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65  y cache.  SQLite
16da0 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79   will.** already
16db0 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44   hold a RESERVED
16dc0 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74   lock on the dat
16dd0 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20  abase file, but 
16de0 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70  it needs.** to p
16df0 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b  romote this lock
16e00 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f   to EXCLUSIVE so
16e10 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69   that it can spi
16e20 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65  ll cache.** page
16e30 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  s into the datab
16e40 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74  ase file without
16e50 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72   harm to concurr
16e60 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20  ent.** readers. 
16e70 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c   ^If it is unabl
16e80 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65  e to promote the
16e90 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20   lock, then the 
16ea0 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63  in-memory.** cac
16eb0 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20  he will be left 
16ec0 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65  in an inconsiste
16ed0 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20  nt state and so 
16ee0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64  the error.** cod
16ef0 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72  e is promoted fr
16f00 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c  om the relativel
16f10 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45  y benign [SQLITE
16f20 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65  _BUSY] to.** the
16f30 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51   more severe [SQ
16f40 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
16f50 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f  ED].  ^This erro
16f60 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e  r code promotion
16f70 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75  .** forces an au
16f80 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b  tomatic rollback
16f90 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e   of the changes.
16fa0 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20    See the.** <a 
16fb0 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77  href="/cvstrac/w
16fc0 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e  iki?p=Corruption
16fd0 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
16fe0 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69  or">.** Corrupti
16ff0 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
17000 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61  rror</a> wiki pa
17010 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73  ge for a discuss
17020 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68  ion of why.** th
17030 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e  is is important.
17040 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
17050 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
17060 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
17070 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63   defined for eac
17080 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
17090 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74  onnection].  Set
170a0 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20  ting a new busy 
170b0 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61  handler clears a
170c0 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ny.** previously
170d0 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20   set handler.)^ 
170e0 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c   ^Note that call
170f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
17100 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20  y_timeout()].** 
17110 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72  will also set or
17120 20 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20   clear the busy 
17130 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  handler..**.** T
17140 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
17150 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65   should not take
17160 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69   any actions whi
17170 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a  ch modify the.**
17180 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17190 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
171a0 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
171b0 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63  er.  Any such ac
171c0 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20  tions.** result 
171d0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
171e0 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20  avior..** .** A 
171f0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73  busy handler mus
17200 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
17210 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17220 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61  ion.** or [prepa
17230 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
17240 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
17250 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f  busy handler..*/
17260 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
17270 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  y_handler(sqlite
17280 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
17290 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  ,int), void*);..
172a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
172b0 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
172c0 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  ut.**.** ^This r
172d0 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
172e0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
172f0 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
17300 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
17310 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
17320 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
17330 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
17340 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20  s locked.  ^The 
17350 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20  handler.** will 
17360 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74  sleep multiple t
17370 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65  imes until at le
17380 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
17390 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
173a0 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75  g.** have accumu
173b0 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61  lated.  ^After a
173c0 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
173d0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
173e0 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61  eping,.** the ha
173f0 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20  ndler returns 0 
17400 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71  which causes [sq
17410 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f  lite3_step()] to
17420 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
17430 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
17440 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
17450 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  D]..**.** ^Calli
17460 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
17470 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74  with an argument
17480 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
17490 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74  ual to zero.** t
174a0 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73  urns off all bus
174b0 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a  y handlers..**.*
174c0 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
174d0 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
174e0 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
174f0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
17500 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
17510 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69  tion] any any gi
17520 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
17530 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
17540 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
17550 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
17560 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
17570 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
17580 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
17590 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
175a0 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
175b0 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f  is cleared.)^.*/
175c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
175d0 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
175e0 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
175f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
17600 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
17610 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
17620 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69  ueries.**.** Thi
17630 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e  s is a legacy in
17640 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20  terface that is 
17650 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61  preserved for ba
17660 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
17670 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66  ility..** Use of
17680 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
17690 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64  is not recommend
176a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  ed..**.** Defini
176b0 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
176c0 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
176d0 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
176e0 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
176f0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
17700 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
17710 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
17720 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
17730 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
17740 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
17750 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
17760 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
17770 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
17780 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
17790 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
177a0 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
177b0 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
177c0 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
177d0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
177e0 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
177f0 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
17800 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
17810 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
17820 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
17830 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
17840 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
17850 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
17860 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
17870 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
17880 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
17890 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
178a0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
178b0 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
178c0 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
178d0 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
178e0 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
178f0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
17900 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
17910 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
17920 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
17930 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
17940 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
17950 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
17960 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
17970 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
17980 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
17990 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
179a0 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
179b0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
179c0 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
179d0 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
179e0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
179f0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
17a00 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
17a10 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
17a20 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
17a30 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
17a40 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
17a50 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
17a60 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
17a70 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
17a80 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
17a90 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
17aa0 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
17ab0 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
17ac0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
17ad0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20  ()]..**.** ^(As 
17ae0 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
17af0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
17b00 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
17b10 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
17b20 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
17b30 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
17b40 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
17b50 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
17b60 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
17b70 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
17b80 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
17b90 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
17ba0 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
17bb0 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
17bc0 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
17bd0 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
17be0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
17bf0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
17c00 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
17c10 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
17c20 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
17c30 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
17c40 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
17c50 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
17c60 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
17c70 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
17c80 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
17c90 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
17ca0 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
17cb0 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
17cc0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
17cd0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
17ce0 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
17cf0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
17d00 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
17d10 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
17d20 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
17d30 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
17d40 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
17d50 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
17d60 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
17d70 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
17d80 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
17d90 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
17da0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
17db0 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
17dc0 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
17dd0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
17de0 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
17df0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
17e00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
17e10 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
17e20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
17e30 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
17e40 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
17e50 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
17e60 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
17e70 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
17e80 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
17e90 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
17ea0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72   and returns a r
17eb0 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
17ec0 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
17ed0 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
17ee0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
17ef0 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63  After the applic
17f00 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ation has finish
17f10 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75  ed with the resu
17f20 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  lt from sqlite3_
17f30 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20  get_table(),.** 
17f40 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65  it must pass the
17f50 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f   result table po
17f60 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
17f70 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
17f80 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c   order to.** rel
17f90 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
17fa0 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65  that was malloce
17fb0 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  d.  Because of t
17fc0 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73  he way the.** [s
17fd0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
17fe0 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20   happens within 
17ff0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
18000 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  e(), the calling
18010 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
18020 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c  t not try to cal
18030 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  l [sqlite3_free(
18040 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e  )] directly.  On
18050 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ly.** [sqlite3_f
18060 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  ree_table()] is 
18070 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20  able to release 
18080 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65  the memory prope
18090 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a  rly and safely..
180a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
180b0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e  3_get_table() in
180c0 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
180d0 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70  mented as a wrap
180e0 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
180f0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20  qlite3_exec()]. 
18100 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
18110 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65  _table() routine
18120 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61   does not have a
18130 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20  ccess.** to any 
18140 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74  internal data st
18150 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69  ructures of SQLi
18160 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c  te.  It uses onl
18170 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20  y the public.** 
18180 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65  interface define
18190 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f  d here.  As a co
181a0 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72  nsequence, error
181b0 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20  s that occur in 
181c0 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c  the.** wrapper l
181d0 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20  ayer outside of 
181e0 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71  the internal [sq
181f0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61  lite3_exec()] ca
18200 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  ll are not.** re
18210 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65  flected in subse
18220 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
18230 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
18240 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
18250 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a  3_errmsg()]..*/.
18260 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
18270 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  table(.  sqlite3
18280 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
18290 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
182a0 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
182b0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a  ar *zSql,     /*
182c0 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
182d0 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ated */.  char *
182e0 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20  **pazResult,    
182f0 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68  /* Results of th
18300 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74  e query */.  int
18310 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20   *pnRow,        
18320 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
18330 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74  result rows writ
18340 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e  ten here */.  in
18350 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20  t *pnColumn,    
18360 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
18370 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20   result columns 
18380 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
18390 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73    char **pzErrms
183a0 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72  g       /* Error
183b0 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
183c0 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c  e */.);.void sql
183d0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
183e0 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a  char **result);.
183f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18400 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e   Formatted Strin
18410 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74  g Printing Funct
18420 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
18430 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
18440 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65  rk-alikes of the
18450 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69   "printf()" fami
18460 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ly of functions.
18470 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ** from the stan
18480 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
18490 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
184a0 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
184b0 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
184c0 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69  f() routines wri
184d0 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75  te their.** resu
184e0 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  lts into memory 
184f0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
18500 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
18510 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73  ..** The strings
18520 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
18530 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20  se two routines 
18540 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c  should be.** rel
18550 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eased by [sqlite
18560 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74  3_free()].  ^Bot
18570 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  h routines retur
18580 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
18590 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  ter if [sqlite3_
185a0 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61  malloc()] is una
185b0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
185c0 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79  enough.** memory
185d0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
185e0 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a  ulting string..*
185f0 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
18600 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
18610 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
18620 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
18630 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
18640 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
18650 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
18660 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
18670 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
18680 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
18690 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
186a0 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
186b0 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
186c0 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
186d0 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
186e0 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
186f0 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
18700 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
18710 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68  nprintf().)^  Th
18720 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
18730 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
18740 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
18750 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
18760 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
18770 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
18780 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74  .  ^(Note also t
18790 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  hat sqlite3_snpr
187a0 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e  intf().** return
187b0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
187c0 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61  ts buffer instea
187d0 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  d of the number 
187e0 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  of.** characters
187f0 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65   actually writte
18800 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  n into the buffe
18810 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74  r.)^  We admit t
18820 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
18830 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
18840 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
18850 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
18860 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
18870 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
18880 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
18890 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
188a0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
188b0 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
188c0 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
188d0 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f  ty..**.** ^As lo
188e0 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
188f0 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
18900 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
18910 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
18920 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
18930 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
18940 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
18950 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69  inated.  ^The fi
18960 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
18970 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
18980 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
18990 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
189a0 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
189b0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
189c0 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
189d0 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
189e0 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
189f0 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
18a00 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
18a10 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
18a20 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
18a30 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76  ) routine is a v
18a40 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f  arargs version o
18a50 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
18a60 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tf()..**.** Thes
18a70 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
18a80 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
18a90 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
18aa0 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
18ab0 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
18ac0 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
18ad0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
18ae0 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
18af0 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72  ual printf() for
18b00 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
18b10 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
18b20 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
18b30 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
18b40 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
18b50 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  s..**.** ^(The %
18b60 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  q option works l
18b70 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69  ike %s in that i
18b80 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20  t substitutes a 
18b90 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
18ba0 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68  * string from th
18bb0 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e  e argument list.
18bc0 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f    But %q also do
18bd0 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27  ubles every '\''
18be0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25   character..** %
18bf0 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f  q is designed fo
18c00 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73  r use inside a s
18c10 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e  tring literal.)^
18c20 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61    By doubling ea
18c30 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61  ch '\''.** chara
18c40 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20  cter it escapes 
18c50 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61  that character a
18c60 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20  nd allows it to 
18c70 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  be inserted into
18c80 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a  .** the string..
18c90 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
18ca0 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74  e, assume the st
18cb0 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54  ring variable zT
18cc0 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78  ext contains tex
18cd0 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
18ce0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
18cf0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
18d00 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20  zText = "It's a 
18d10 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20  happy day!";.** 
18d20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
18d30 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61  te>.**.** One ca
18d40 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20  n use this text 
18d50 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
18d60 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ent as follows:.
18d70 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
18d80 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
18d90 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
18da0 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
18db0 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
18dc0 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74  ES('%q')", zText
18dd0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
18de0 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
18df0 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
18e00 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
18e10 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
18e20 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63  quote>.**.** Bec
18e30 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d  ause the %q form
18e40 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65  at string is use
18e50 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72  d, the '\'' char
18e60 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a  acter in zText.*
18e70 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64  * is escaped and
18e80 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74   the SQL generat
18e90 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ed is as follows
18ea0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
18eb0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
18ec0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
18ed0 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61   VALUES('It''s a
18ee0 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a   happy day!').**
18ef0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
18f00 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
18f10 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64  is correct.  Had
18f20 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74   we used %s inst
18f30 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67  ead of %q, the g
18f40 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20  enerated SQL.** 
18f50 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65  would have looke
18f60 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  d like this:.**.
18f70 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
18f80 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
18f90 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
18fa0 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79  ES('It's a happy
18fb0 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72   day!');.** </pr
18fc0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
18fd0 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e  **.** This secon
18fe0 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20  d example is an 
18ff0 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72  SQL syntax error
19000 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20  .  As a general 
19010 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a  rule you should.
19020 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71  ** always use %q
19030 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77   instead of %s w
19040 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65  hen inserting te
19050 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67  xt into a string
19060 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20   literal..**.** 
19070 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  ^(The %Q option 
19080 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
19090 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
190a0 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
190b0 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
190c0 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
190d0 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69  al string.  Addi
190e0 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65  tionally, if the
190f0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
19100 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69  e.** argument li
19110 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  st is a NULL poi
19120 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74  nter, %Q substit
19130 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e  utes the text "N
19140 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a  ULL" (without.**
19150 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e   single quotes).
19160 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d  )^  So, for exam
19170 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73  ple, one could s
19180 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ay:.**.** <block
19190 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
191a0 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
191b0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
191c0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
191d0 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65  VALUES(%Q)", zTe
191e0 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
191f0 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
19200 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
19210 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
19220 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
19230 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
19240 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69  he code above wi
19250 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72  ll render a corr
19260 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ect SQL statemen
19270 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a  t in the zSQL.**
19280 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69   variable even i
19290 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69  f the zText vari
192a0 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70  able is a NULL p
192b0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ointer..**.** ^(
192c0 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74  The "%z" formatt
192d0 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73  ing option works
192e0 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77   like "%s" but w
192f0 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
19300 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
19310 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
19320 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
19330 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
19340 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
19350 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
19360 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
19370 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72  tring.)^.*/.char
19380 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   *sqlite3_mprint
19390 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e  f(const char*,..
193a0 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
193b0 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
193c0 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
193d0 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
193e0 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
193f0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
19400 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
19410 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e  te3_vsnprintf(in
19420 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
19430 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a  ar*, va_list);..
19440 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19450 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
19460 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a  n Subsystem.**.*
19470 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
19480 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72  e uses these thr
19490 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
194a0 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
194b0 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
194c0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
194d0 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
194e0 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
194f0 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
19500 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
19510 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
19520 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
19530 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
19540 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
19550 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
19560 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
19570 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
19580 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
19590 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
195a0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
195b0 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
195c0 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
195d0 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
195e0 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
195f0 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
19600 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  r..** ^If sqlite
19610 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
19620 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
19630 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
19640 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
19650 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
19660 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61  ter.  ^If the pa
19670 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
19680 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
19690 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
196a0 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
196b0 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
196c0 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
196d0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  nter..**.** ^Cal
196e0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
196f0 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
19700 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
19710 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
19720 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
19730 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
19740 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
19750 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
19760 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
19770 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
19780 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
19790 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
197a0 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
197b0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
197c0 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
197d0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
197e0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
197f0 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
19800 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
19810 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
19820 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
19830 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
19840 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
19850 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
19860 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
19870 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
19880 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
19890 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
198a0 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
198b0 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
198c0 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
198d0 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
198e0 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
198f0 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
19900 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
19910 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
19920 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
19930 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
19940 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
19950 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
19960 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
19970 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
19980 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e  te3_realloc() in
19990 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
199a0 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
199b0 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
199c0 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74  ocation to be at
199d0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20   least N bytes, 
199e0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
199f0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
19a00 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20  er.  The memory 
19a10 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
19a20 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20   resized is the 
19a30 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
19a40 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66  er.)^ ^ If the f
19a50 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
19a60 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
19a70 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  c().** is a NULL
19a80 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
19a90 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
19aa0 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
19ab0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
19ac0 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20  lloc(N) where N 
19ad0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  is the second pa
19ae0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
19af0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
19b00 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
19b10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
19b20 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69  ite3_realloc() i
19b30 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67  s zero or.** neg
19b40 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62  ative then the b
19b50 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74  ehavior is exact
19b60 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63  ly the same as c
19b70 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
19b80 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20  3_free(P) where 
19b90 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  P is the first p
19ba0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
19bb0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
19bc0 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  * ^sqlite3_reall
19bd0 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  oc() returns a p
19be0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
19bf0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
19c00 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
19c10 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
19c20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65  NULL if sufficie
19c30 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61  nt memory is una
19c40 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66  vailable..** ^If
19c50 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
19c60 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
19c70 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
19c80 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
19c90 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
19ca0 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
19cb0 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
19cc0 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
19cd0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
19ce0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
19cf0 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
19d00 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
19d10 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
19d20 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
19d30 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  rns NULL, then t
19d40 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
19d50 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72  ion.** is not fr
19d60 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
19d70 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
19d80 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
19d90 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  c() and sqlite3_
19da0 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
19db0 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74  always aligned t
19dc0 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20  o at least an 8 
19dd0 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f  byte boundary, o
19de0 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65  r to a.** 4 byte
19df0 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65   boundary if the
19e00 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f   [SQLITE_4_BYTE_
19e10 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20  ALIGNED_MALLOC] 
19e20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
19e30 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a  option is used..
19e40 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20  **.** In SQLite 
19e50 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e  version 3.5.0 an
19e60 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20  d 3.5.1, it was 
19e70 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69  possible to defi
19e80 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45  ne.** the SQLITE
19e90 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c  _OMIT_MEMORY_ALL
19ea0 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f  OCATION which wo
19eb0 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75  uld cause the bu
19ec0 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  ilt-in.** implem
19ed0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73  entation of thes
19ee0 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  e routines to be
19ef0 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20   omitted.  That 
19f00 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
19f10 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69   no longer provi
19f20 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74  ded.  Only built
19f30 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
19f40 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65  ators can be use
19f50 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e  d..**.** The Win
19f60 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63  dows OS interfac
19f70 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a  e layer calls.**
19f80 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
19f90 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
19fa0 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
19fb0 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
19fc0 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
19fd0 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
19fe0 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
19ff0 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
1a000 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
1a010 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
1a020 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
1a030 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
1a040 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
1a050 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61  ocation errors a
1a060 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74  re detected, but
1a070 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70  .** they are rep
1a080 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53  orted back as [S
1a090 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
1a0a0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
1a0b0 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e  ERR] rather than
1a0c0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
1a0d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  .**.** The point
1a0e0 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
1a0f0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1a100 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1a110 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  alloc()].** must
1a120 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20   be either NULL 
1a130 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73  or else pointers
1a140 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
1a150 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61   prior.** invoca
1a160 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
1a170 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
1a180 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1a190 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e  ] that have.** n
1a1a0 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65  ot yet been rele
1a1b0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ased..**.** The 
1a1c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
1a1d0 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69   not read or wri
1a1e0 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a  te any part of.*
1a1f0 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  * a block of mem
1a200 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73  ory after it has
1a210 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75   been released u
1a220 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
1a230 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c  _free()] or [sql
1a240 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e  ite3_realloc()].
1a250 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
1a260 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76  3_malloc(int);.v
1a270 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
1a280 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
1a290 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
1a2a0 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  ree(void*);../*.
1a2b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
1a2c0 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74  ory Allocator St
1a2d0 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53  atistics.**.** S
1a2e0 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
1a2f0 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
1a300 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
1a310 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
1a320 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
1a330 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
1a340 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
1a350 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1a360 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
1a370 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
1a380 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
1a390 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
1a3a0 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
1a3b0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
1a3c0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75  mory_used()] rou
1a3d0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
1a3e0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
1a3f0 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75  .** of memory cu
1a400 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64  rrently outstand
1a410 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75  ing (malloced bu
1a420 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a  t not freed)..**
1a430 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1a440 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1a450 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1a460 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  ns the maximum.*
1a470 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69  * value of [sqli
1a480 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1a490 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67  )] since the hig
1a4a0 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
1a4b0 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20  was last reset. 
1a4c0 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
1a4d0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1a4e0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1a4f0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1a500 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1a510 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79  r()] include any
1a520 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64   overhead.** add
1a530 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20  ed by SQLite in 
1a540 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  its implementati
1a550 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
1a560 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74  alloc()],.** but
1a570 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64   not overhead ad
1a580 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75  ded by the any u
1a590 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d  nderlying system
1a5a0 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74   library.** rout
1a5b0 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74  ines that [sqlit
1a5c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79  e3_malloc()] may
1a5d0 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   call..**.** ^Th
1a5e0 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61  e memory high-wa
1a5f0 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65  ter mark is rese
1a600 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74  t to the current
1a610 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71   value of.** [sq
1a620 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1a630 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  d()] if and only
1a640 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1a650 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
1a660 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1a670 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e  r()] is true.  ^
1a680 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
1a690 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
1a6a0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1a6b0 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69  er(1)] is the hi
1a6c0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1a6d0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65   prior to the re
1a6e0 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  set..*/.sqlite3_
1a6f0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
1a700 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b  mory_used(void);
1a710 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
1a720 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1a730 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65  ghwater(int rese
1a740 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  tFlag);../*.** C
1a750 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d  API3REF: Pseudo-
1a760 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65  Random Number Ge
1a770 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51  nerator.**.** SQ
1a780 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20  Lite contains a 
1a790 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65  high-quality pse
1a7a0 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65  udo-random numbe
1a7b0 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e  r generator (PRN
1a7c0 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65  G) used to.** se
1a7d0 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57  lect random [ROW
1a7e0 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65  ID | ROWIDs] whe
1a7f0 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20  n inserting new 
1a800 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74  records into a t
1a810 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72  able that.** alr
1a820 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61  eady uses the la
1a830 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b  rgest possible [
1a840 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e  ROWID].  The PRN
1a850 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66  G is also used f
1a860 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d  or.** the build-
1a870 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20  in random() and 
1a880 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c  randomblob() SQL
1a890 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69   functions.  Thi
1a8a0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
1a8b0 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  ws.** applicatio
1a8c0 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ns to access the
1a8d0 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f   same PRNG for o
1a8e0 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a  ther purposes..*
1a8f0 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  *.** ^A call to 
1a900 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  this routine sto
1a910 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72  res N bytes of r
1a920 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62  andomness into b
1a930 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e  uffer P..**.** ^
1a940 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
1a950 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69  his routine is i
1a960 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69  nvoked (either i
1a970 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a  nternally or by.
1a980 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
1a990 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20  on) the PRNG is 
1a9a0 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e  seeded using ran
1a9b0 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
1a9c0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61  .** from the xRa
1a9d0 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
1a9e0 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
1a9f0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1aa00 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20  ect..** ^On all 
1aa10 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
1aa20 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75  ations, the pseu
1aa30 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
1aa40 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
1aa50 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
1aa60 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
1aa70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
1aa80 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
1aa90 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69  * method..*/.voi
1aaa0 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
1aab0 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
1aac0 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
1aad0 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
1aae0 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
1aaf0 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  n Callbacks.**.*
1ab00 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
1ab10 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74  registers an aut
1ab20 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ab30 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
1ab40 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
1ab50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70  connection], sup
1ab60 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  plied in the fir
1ab70 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  st argument..** 
1ab80 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
1ab90 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1aba0 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65  ked as SQL state
1abb0 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20  ments are being 
1abc0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b  compiled.** by [
1abd0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1abe0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
1abf0 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ts [sqlite3_prep
1ac00 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  are_v2()],.** [s
1ac10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1ac20 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1ac30 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
1ac40 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a  .  ^At various.*
1ac50 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20  * points during 
1ac60 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  the compilation 
1ac70 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69  process, as logi
1ac80 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74  c is being creat
1ac90 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d  ed.** to perform
1aca0 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73   various actions
1acb0 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  , the authorizer
1acc0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1acd0 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69  oked to.** see i
1ace0 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20  f those actions 
1acf0 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54  are allowed.  ^T
1ad00 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1ad10 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a  llback should.**
1ad20 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1ad30 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65  OK] to allow the
1ad40 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45   action, [SQLITE
1ad50 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61  _IGNORE] to disa
1ad60 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63  llow the.** spec
1ad70 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20  ific action but 
1ad80 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74  allow the SQL st
1ad90 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69  atement to conti
1ada0 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  nue to be.** com
1adb0 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54  piled, or [SQLIT
1adc0 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65  E_DENY] to cause
1add0 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20   the entire SQL 
1ade0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a  statement to be.
1adf0 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68  ** rejected with
1ae00 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20   an error.  ^If 
1ae10 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1ae20 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
1ae30 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ** any value oth
1ae40 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1ae50 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45  IGNORE], [SQLITE
1ae60 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  _OK], or [SQLITE
1ae70 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74  _DENY].** then t
1ae80 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
1ae90 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
1aea0 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
1aeb0 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74  t triggered.** t
1aec0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  he authorizer wi
1aed0 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
1aee0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
1aef0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61  *.** When the ca
1af00 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1af10 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74  SQLITE_OK], that
1af20 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61   means the opera
1af30 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65  tion.** requeste
1af40 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20  d is ok.  ^When 
1af50 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1af60 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  urns [SQLITE_DEN
1af70 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  Y], the.** [sqli
1af80 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1af90 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
1afa0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
1afb0 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f  red the.** autho
1afc0 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
1afd0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
1afe0 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67  ssage explaining
1aff0 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20   that.** access 
1b000 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a  is denied. .**.*
1b010 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
1b020 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1b030 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1b040 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
1b050 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
1b060 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
1b070 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1b080 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
1b090 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
1b0a0 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
1b0b0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
1b0c0 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f  integer [SQLITE_
1b0d0 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f  COPY | action co
1b0e0 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69  de] that specifi
1b0f0 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63  es.** the partic
1b100 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62  ular action to b
1b110 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54  e authorized. ^T
1b120 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68  he third through
1b130 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
1b140 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  s.** to the call
1b150 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65  back are zero-te
1b160 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
1b170 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64   that contain ad
1b180 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61  ditional.** deta
1b190 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
1b1a0 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
1b1b0 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rized..**.** ^If
1b1c0 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
1b1d0 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44   is [SQLITE_READ
1b1e0 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c  ].** and the cal
1b1f0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1b200 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
1b210 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  en the.** [prepa
1b220 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73  red statement] s
1b230 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73  tatement is cons
1b240 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74  tructed to subst
1b250 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20  itute.** a NULL 
1b260 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f  value in place o
1b270 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
1b280 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  mn that would ha
1b290 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20  ve.** been read 
1b2a0 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
1b2b0 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
1b2c0 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  .  The [SQLITE_I
1b2d0 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e  GNORE].** return
1b2e0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1b2f0 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65  deny an untruste
1b300 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f  d user access to
1b310 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63   individual.** c
1b320 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c  olumns of a tabl
1b330 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  e..** ^If the ac
1b340 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
1b350 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64  LITE_DELETE] and
1b360 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1b370 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
1b380 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
1b390 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61  e [DELETE] opera
1b3a0 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75  tion proceeds bu
1b3b0 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61  t the.** [trunca
1b3c0 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d  te optimization]
1b3d0 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64   is disabled and
1b3e0 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65   all rows are de
1b3f0 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c  leted individual
1b400 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74  ly..**.** An aut
1b410 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20  horizer is used 
1b420 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  when [sqlite3_pr
1b430 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e  epare | preparin
1b440 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  g].** SQL statem
1b450 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74  ents from an unt
1b460 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74  rusted source, t
1b470 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  o ensure that th
1b480 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
1b490 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74  .** do not try t
1b4a0 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68  o access data th
1b4b0 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77  ey are not allow
1b4c0 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68  ed to see, or th
1b4d0 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
1b4e0 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65  * try to execute
1b4f0 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65   malicious state
1b500 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67  ments that damag
1b510 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  e the database. 
1b520 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
1b530 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
1b540 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72  may allow a user
1b550 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72   to enter arbitr
1b560 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69  ary.** SQL queri
1b570 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f  es for evaluatio
1b580 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e  n by a database.
1b590 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63    But the applic
1b5a0 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ation does.** no
1b5b0 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20  t want the user 
1b5c0 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61  to be able to ma
1b5d0 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61  ke arbitrary cha
1b5e0 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  nges to the.** d
1b5f0 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74  atabase.  An aut
1b600 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68  horizer could th
1b610 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61  en be put in pla
1b620 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20  ce while the.** 
1b630 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c  user-entered SQL
1b640 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74   is being [sqlit
1b650 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
1b660 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64  pared] that.** d
1b670 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68  isallows everyth
1b680 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45  ing except [SELE
1b690 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  CT] statements..
1b6a0 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
1b6b0 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20  ns that need to 
1b6c0 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d  process SQL from
1b6d0 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
1b6e0 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f  es.** might also
1b6f0 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69   consider loweri
1b700 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69  ng resource limi
1b710 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ts using [sqlite
1b720 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e  3_limit()].** an
1b730 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62  d limiting datab
1b740 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74  ase size using t
1b750 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  he [max_page_cou
1b760 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20  nt] [PRAGMA].** 
1b770 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75  in addition to u
1b780 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a  sing an authoriz
1b790 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79  er..**.** ^(Only
1b7a0 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
1b7b0 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
1b7c0 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
1b7d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1b7e0 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
1b7f0 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
1b800 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1b810 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
1b820 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
1b830 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65  )^  ^Disable the
1b840 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69   authorizer by i
1b850 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c  nstalling a NULL
1b860 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68   callback..** Th
1b870 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  e authorizer is 
1b880 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
1b890 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ult..**.** The a
1b8a0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1b8b0 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
1b8c0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
1b8d0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
1b8e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b8f0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
1b900 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1b910 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74  callback..** Not
1b920 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
1b930 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
1b940 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
1b950 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
1b960 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
1b970 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
1b980 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
1b990 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
1b9a0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
1b9b0 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  * ^When [sqlite3
1b9c0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
1b9d0 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72  s used to prepar
1b9e0 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  e a statement, t
1b9f0 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  he.** statement 
1ba00 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70  might be re-prep
1ba10 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c  ared during [sql
1ba20 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65  ite3_step()] due
1ba30 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61   to a .** schema
1ba40 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c   change.  Hence,
1ba50 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1ba60 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74   should ensure t
1ba70 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  hat the.** corre
1ba80 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ct authorizer ca
1ba90 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69  llback remains i
1baa0 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74  n place during t
1bab0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
1bac0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65  ()]..**.** ^Note
1bad0 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
1bae0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1baf0 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
1bb00 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ring.** [sqlite3
1bb10 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
1bb20 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
1bb30 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
1bb40 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
1bb50 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
1bb60 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
1bb70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
1bb80 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74   unless.** as st
1bb90 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76  ated in the prev
1bba0 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20  ious paragraph, 
1bbb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
1bbc0 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65  nvokes.** sqlite
1bbd0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74  3_prepare_v2() t
1bbe0 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74  o reprepare a st
1bbf0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20  atement after a 
1bc00 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a  schema change..*
1bc10 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65  /.int sqlite3_se
1bc20 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20  t_authorizer(.  
1bc30 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20  sqlite3*,.  int 
1bc40 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69  (*xAuth)(void*,i
1bc50 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  nt,const char*,c
1bc60 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1bc70 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
1bc80 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73  r*),.  void *pUs
1bc90 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  erData.);../*.**
1bca0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
1bcb0 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64  rizer Return Cod
1bcc0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
1bcd0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1bce0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
1bcf0 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
1bd00 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74  ion] must.** ret
1bd10 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49  urn either [SQLI
1bd20 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66  TE_OK] or one of
1bd30 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74   these two const
1bd40 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  ants in order.**
1bd50 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74   to signal SQLit
1bd60 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  e whether or not
1bd70 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70   the action is p
1bd80 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74  ermitted.  See t
1bd90 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
1bda0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
1bdb0 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d  authorizer docum
1bdc0 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64  entation] for ad
1bdd0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
1bde0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e  rmation..**.** N
1bdf0 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f  ote that SQLITE_
1be00 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75  IGNORE is also u
1be10 73 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45  sed as a [SQLITE
1be20 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75  _ROLLBACK | retu
1be30 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d  rn code].** from
1be40 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74   the [sqlite3_vt
1be50 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
1be60 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
1be70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1be80 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
1be90 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
1bea0 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
1beb0 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
1bec0 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
1bed0 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
1bee0 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
1bef0 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
1bf00 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
1bf10 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
1bf20 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
1bf30 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
1bf40 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1bf50 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
1bf60 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
1bf70 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
1bf80 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
1bf90 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
1bfa0 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
1bfb0 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
1bfc0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
1bfd0 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
1bfe0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
1bff0 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
1c000 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
1c010 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
1c020 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
1c030 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
1c040 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
1c050 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
1c060 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
1c070 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
1c080 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
1c090 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
1c0a0 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
1c0b0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
1c0c0 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
1c0d0 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
1c0e0 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
1c0f0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
1c100 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
1c110 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
1c120 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
1c130 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
1c140 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
1c150 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
1c160 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
1c170 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
1c180 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
1c190 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
1c1a0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1c1b0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1c1c0 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
1c1d0 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
1c1e0 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
1c1f0 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
1c200 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
1c210 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1c220 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
1c230 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
1c240 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
1c250 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
1c260 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
1c270 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
1c280 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
1c290 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
1c2a0 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
1c2b0 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
1c2c0 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
1c2d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c2e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c2f0 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
1c300 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
1c310 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
1c320 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1c330 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
1c340 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
1c350 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1c360 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1c370 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1c380 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
1c390 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1c3a0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1c3b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1c3c0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1c3d0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
1c3e0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1c3f0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1c400 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1c410 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1c420 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
1c430 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1c440 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1c450 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1c460 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1c470 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
1c480 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1c490 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1c4a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1c4b0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1c4c0 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
1c4d0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1c4e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1c4f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1c500 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
1c510 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
1c520 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1c530 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1c540 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c550 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
1c560 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
1c570 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1c580 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1c590 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c5a0 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
1c5b0 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
1c5c0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1c5d0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1c5e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c5f0 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
1c600 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
1c610 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1c620 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1c630 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c640 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
1c650 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
1c660 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1c670 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1c680 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1c690 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
1c6a0 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
1c6b0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1c6c0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1c6d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1c6e0 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
1c6f0 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
1c700 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1c710 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1c720 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1c730 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
1c740 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
1c750 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1c760 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1c770 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1c780 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
1c790 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
1c7a0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1c7b0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1c7c0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1c7d0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
1c7e0 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
1c7f0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1c800 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1c810 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
1c820 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
1c830 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
1c840 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1c850 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1c860 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
1c870 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
1c880 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1c890 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1c8a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1c8b0 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
1c8c0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
1c8d0 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
1c8e0 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
1c8f0 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
1c900 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
1c910 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
1c920 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1c930 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
1c940 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1c950 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
1c960 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
1c970 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
1c980 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1c990 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1c9a0 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
1c9b0 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
1c9c0 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
1c9d0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1c9e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1c9f0 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
1ca00 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
1ca10 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1ca20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
1ca30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ca40 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
1ca50 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
1ca60 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
1ca70 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1ca80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ca90 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
1caa0 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
1cab0 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
1cac0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1cad0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1cae0 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
1caf0 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
1cb00 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
1cb10 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1cb20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1cb30 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
1cb40 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
1cb50 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
1cb60 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1cb70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1cb80 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
1cb90 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
1cba0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1cbb0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1cbc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1cbd0 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
1cbe0 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
1cbf0 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
1cc00 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
1cc10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1cc20 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
1cc30 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
1cc40 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
1cc50 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1cc60 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
1cc70 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
1cc80 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
1cc90 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
1cca0 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
1ccb0 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
1ccc0 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
1ccd0 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
1cce0 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
1ccf0 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
1cd00 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
1cd10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1cd20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
1cd30 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   used */../*.** 
1cd40 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e  CAPI3REF: Tracin
1cd50 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20  g And Profiling 
1cd60 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1cd70 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1cd80 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
1cd90 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
1cda0 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a  can be used for.
1cdb0 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70  ** tracing and p
1cdc0 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65  rofiling the exe
1cdd0 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74  cution of SQL st
1cde0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
1cdf0 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
1ce00 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
1ce10 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61  d by sqlite3_tra
1ce20 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ce() is invoked 
1ce30 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69  at.** various ti
1ce40 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20  mes when an SQL 
1ce50 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69  statement is bei
1ce60 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74  ng run by [sqlit
1ce70 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e  e3_step()]..** ^
1ce80 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
1ce90 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e() callback is 
1cea0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55  invoked with a U
1ceb0 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
1cec0 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61  f the.** SQL sta
1ced0 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74  tement text as t
1cee0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
1cef0 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
1cf00 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69  ing..** ^(Additi
1cf10 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61  onal sqlite3_tra
1cf20 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d  ce() callbacks m
1cf30 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73  ight occur.** as
1cf40 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20   each triggered 
1cf50 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
1cf60 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
1cf70 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
1cf80 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
1cf90 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
1cfa0 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
1cfb0 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e  s the trigger.)^
1cfc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
1cfd0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
1cfe0 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
1cff0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
1d000 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
1d010 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
1d020 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68  t finishes.  ^Th
1d030 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
1d040 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
1d050 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
1d060 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
1d070 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
1d080 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
1d090 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
1d0a0 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
1d0b0 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70   to run.  ^The p
1d0c0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a  rofile callback.
1d0d0 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e  ** time is in un
1d0e0 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  its of nanosecon
1d0f0 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  ds, however the 
1d100 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
1d110 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c  tation.** is onl
1d120 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c  y capable of mil
1d130 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74  lisecond resolut
1d140 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c  ion so the six l
1d150 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  east significant
1d160 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68  .** digits in th
1d170 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69  e time are meani
1d180 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20  ngless.  Future 
1d190 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1d1a0 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76  te.** might prov
1d1b0 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f  ide greater reso
1d1c0 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72  lution on the pr
1d1d0 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  ofiler callback.
1d1e0 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
1d1f0 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74  _profile() funct
1d200 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ion is considere
1d210 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  d experimental a
1d220 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74  nd is.** subject
1d230 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75   to change in fu
1d240 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
1d250 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64   SQLite..*/.void
1d260 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
1d270 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
1d280 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
1d290 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
1d2a0 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  *);.SQLITE_EXPER
1d2b0 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71  IMENTAL void *sq
1d2c0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
1d2d0 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
1d2e0 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
1d2f0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
1d300 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
1d310 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1d320 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
1d330 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a  gress Callbacks.
1d340 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1d350 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1d360 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74  ler(D,N,X,P) int
1d370 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
1d380 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  e callback.** fu
1d390 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69  nction X to be i
1d3a0 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
1d3b0 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
1d3c0 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
1d3d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
1d3e0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
1d3f0 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tep()] and [sqli
1d400 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
1d410 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65   for.** database
1d420 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
1d430 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
1d440 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
1d450 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
1d460 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
1d470 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
1d480 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ry..**.** ^The p
1d490 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61  arameter P is pa
1d4a0 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
1d4b0 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
1d4c0 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61  er to the .** ca
1d4d0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1d4e0 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  X.  ^The paramet
1d4f0 65 72 20 4e 20 69 73 20 74 68 65 20 6e 75 6d 62  er N is the numb
1d500 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75  er of .** [virtu
1d510 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72  al machine instr
1d520 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72  uctions] that ar
1d530 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77  e evaluated betw
1d540 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a  een successive.*
1d550 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
1d560 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e   the callback X.
1d570 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73  .**.** ^Only a s
1d580 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68  ingle progress h
1d590 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65  andler may be de
1d5a0 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d  fined at one tim
1d5b0 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61  e per.** [databa
1d5c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20  se connection]; 
1d5d0 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72  setting a new pr
1d5e0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
1d5f0 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c  ancels the.** ol
1d600 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67  d one.  ^Setting
1d610 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20   parameter X to 
1d620 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68  NULL disables th
1d630 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1d640 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67  er..** ^The prog
1d650 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20  ress handler is 
1d660 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79  also disabled by
1d670 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20   setting N to a 
1d680 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68  value less.** th
1d690 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  an 1..**.** ^If 
1d6a0 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
1d6b0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
1d6c0 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
1d6d0 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
1d6e0 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
1d6f0 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
1d700 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
1d710 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
1d720 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
1d730 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
1d740 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
1d750 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
1d760 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
1d770 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
1d780 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
1d790 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1d7a0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1d7b0 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73  oked the progres
1d7c0 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f  s handler..** No
1d7d0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
1d7e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
1d7f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
1d800 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
1d810 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
1d820 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
1d830 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
1d840 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
1d850 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
1d860 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
1d870 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
1d880 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20  (sqlite3*, int, 
1d890 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
1d8a0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1d8b0 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20  PI3REF: Opening 
1d8c0 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43  A New Database C
1d8d0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onnection.**.** 
1d8e0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1d8f0 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
1d900 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20  atabase file as 
1d910 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
1d920 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72   .** filename ar
1d930 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
1d940 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
1d950 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
1d960 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
1d970 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1d980 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1d990 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
1d9a0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1d9b0 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
1d9c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1d9d0 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
1d9e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
1d9f0 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
1da00 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
1da10 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
1da20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
1da30 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
1da40 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
1da50 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
1da60 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
1da70 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1da80 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
1da90 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
1daa0 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
1dab0 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
1dac0 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
1dad0 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
1dae0 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
1daf0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1db00 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
1db10 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
1db20 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
1db30 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
1db40 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
1db50 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
1db60 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
1db70 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
1db80 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
1db90 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1dba0 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
1dbb0 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
1dbc0 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
1dbd0 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
1dbe0 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
1dbf0 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
1dc00 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
1dc10 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
1dc20 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
1dc30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
1dc40 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
1dc50 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  the database wil
1dc60 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a  l be UTF-8 if.**
1dc70 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1dc80 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
1dc90 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  v2() is called a
1dca0 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20  nd.** UTF-16 in 
1dcb0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
1dcc0 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33  order if sqlite3
1dcd0 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65  _open16() is use
1dce0 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  d..**.** Whether
1dcf0 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
1dd00 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
1dd10 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
1dd20 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74  rces.** associat
1dd30 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
1dd40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1dd50 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
1dd60 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a  be released by.*
1dd70 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  * passing it to 
1dd80 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
1dd90 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
1dda0 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
1ddb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1ddc0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74  e3_open_v2() int
1ddd0 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b  erface works lik
1dde0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
1ddf0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
1de00 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61  it accepts two a
1de10 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65  dditional parame
1de20 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f  ters for additio
1de30 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f  nal control.** o
1de40 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61  ver the new data
1de50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
1de60 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61    ^(The flags pa
1de70 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71  rameter to.** sq
1de80 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1de90 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a  can take one of.
1dea0 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
1deb0 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f   three values, o
1dec0 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
1ded0 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
1dee0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1def0 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
1df00 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20  PEN_FULLMUTEX], 
1df10 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
1df20 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53  REDCACHE],.** [S
1df30 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
1df40 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72  TECACHE], and/or
1df50 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
1df60 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a  I] flags:)^.**.*
1df70 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e  * <dl>.** ^(<dt>
1df80 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1df90 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  DONLY]</dt>.** <
1dfa0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1dfb0 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61  is opened in rea
1dfc0 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66  d-only mode.  If
1dfd0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
1dfe0 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64  es not.** alread
1dff0 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
1e000 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
1e010 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1e020 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
1e030 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a  EADWRITE]</dt>.*
1e040 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
1e050 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
1e060 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
1e070 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
1e080 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20  , or reading.** 
1e090 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65  only if the file
1e0a0 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
1e0b0 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61  ted by the opera
1e0c0 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e  ting system.  In
1e0d0 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20   either.** case 
1e0e0 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73  the database mus
1e0f0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  t already exist,
1e100 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   otherwise an er
1e110 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
1e120 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1e130 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
1e140 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
1e150 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1e160 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
1e170 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1e180 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
1e190 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61  g and writing, a
1e1a0 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66  nd is created if
1e1b0 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
1e1c0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
1e1d0 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
1e1e0 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
1e1f0 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
1e200 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
1e210 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
1e220 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  ().</dd>)^.** </
1e230 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  dl>.**.** If the
1e240 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
1e250 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1e260 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  2() is not one o
1e270 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
1e280 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
1e290 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  e optionally com
1e2a0 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72  bined with other
1e2b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1e2c0 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49  _READONLY | SQLI
1e2d0 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a  TE_OPEN_* bits].
1e2e0 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
1e2f0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
1e300 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
1e310 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
1e320 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
1e330 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  et, then the dat
1e340 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e350 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65  .** opens in the
1e360 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   multi-thread [t
1e370 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
1e380 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69  s long as the si
1e390 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d  ngle-thread.** m
1e3a0 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ode has not been
1e3b0 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
1e3c0 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
1e3d0 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  me.  ^If the.** 
1e3e0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
1e3f0 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  LMUTEX] flag is 
1e400 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74  set then the dat
1e410 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e420 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65   opens.** in the
1e430 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
1e440 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c  eading mode] unl
1e450 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  ess single-threa
1e460 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75  d was.** previou
1e470 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20  sly selected at 
1e480 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
1e490 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e  start-time..** ^
1e4a0 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
1e4b0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c  _SHAREDCACHE] fl
1e4c0 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
1e4d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1e4e0 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69  n to be.** eligi
1e4f0 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72  ble to use [shar
1e500 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20  ed cache mode], 
1e510 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
1e520 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
1e530 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
1e540 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73  enabled using [s
1e550 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
1e560 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20  ared_cache()].  
1e570 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ^The.** [SQLITE_
1e580 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
1e590 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
1e5a0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1e5b0 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a  ection to not.**
1e5c0 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20   participate in 
1e5d0 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
1e5e0 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69  de] even if it i
1e5f0 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
1e600 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
1e610 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1e620 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
1e630 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
1e640 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
1e650 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
1e660 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
1e670 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
1e680 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
1e690 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
1e6a0 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
1e6b0 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72  e.  ^If the four
1e6c0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
1e6d0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
1e6e0 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
1e6f0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
1e700 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
1e710 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
1e720 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d  ilename is ":mem
1e730 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72  ory:", then a pr
1e740 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
1e750 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
1e760 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65  ase.** is create
1e770 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  d for the connec
1e780 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d  tion.  ^This in-
1e790 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20  memory database 
1e7a0 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e  will vanish when
1e7b0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1e7c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
1e7d0 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76  losed.  Future v
1e7e0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1e7f0 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20  e might.** make 
1e800 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61  use of additiona
1e810 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61  l special filena
1e820 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77  mes that begin w
1e830 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72  ith the ":" char
1e840 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20  acter..** It is 
1e850 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
1e860 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
1e870 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c   filename actual
1e880 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69  ly does begin wi
1e890 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72  th.** a ":" char
1e8a0 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64  acter you should
1e8b0 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65   prefix the file
1e8c0 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68  name with a path
1e8d0 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20  name such as.** 
1e8e0 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d  "./" to avoid am
1e8f0 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  biguity..**.** ^
1e900 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
1e910 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  is an empty stri
1e920 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  ng, then a priva
1e930 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a  te, temporary.**
1e940 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73   on-disk databas
1e950 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65  e will be create
1e960 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74  d.  ^This privat
1e970 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
1e980 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  be.** automatica
1e990 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73  lly deleted as s
1e9a0 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62  oon as the datab
1e9b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
1e9c0 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
1e9d0 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  [[URI filenames 
1e9e0 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  in sqlite3_open(
1e9f0 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65  )]] <h3>URI File
1ea00 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  names</h3>.**.**
1ea10 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61   ^If [URI filena
1ea20 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69  me] interpretati
1ea30 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61  on is enabled, a
1ea40 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  nd the filename 
1ea50 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69  argument.** begi
1ea60 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c  ns with "file:",
1ea70 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61   then the filena
1ea80 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  me is interprete
1ea90 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49  d as a URI. ^URI
1eaa0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  .** filename int
1eab0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
1eac0 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53  nabled if the [S
1ead0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
1eae0 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69  flag is.** set i
1eaf0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
1eb00 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
1eb10 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69  _open_v2(), or i
1eb20 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e  f it has.** been
1eb30 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c   enabled globall
1eb40 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  y using the [SQL
1eb50 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20  ITE_CONFIG_URI] 
1eb60 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a  option with the.
1eb70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
1eb80 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20  ig()] method or 
1eb90 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  by the [SQLITE_U
1eba0 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d  SE_URI] compile-
1ebb0 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
1ebc0 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  As of SQLite ver
1ebd0 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20  sion 3.7.7, URI 
1ebe0 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
1ebf0 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65  etation is turne
1ec00 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61  d off.** by defa
1ec10 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20  ult, but future 
1ec20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
1ec30 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20  te might enable 
1ec40 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  URI filename.** 
1ec50 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62  interpretation b
1ec60 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20  y default.  See 
1ec70 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d  "[URI filenames]
1ec80 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  " for additional
1ec90 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
1eca0 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  .**.** URI filen
1ecb0 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20  ames are parsed 
1ecc0 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43  according to RFC
1ecd0 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55   3986. ^If the U
1ece0 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a  RI contains an.*
1ecf0 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65  * authority, the
1ed00 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74  n it must be eit
1ed10 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72  her an empty str
1ed20 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e  ing or the strin
1ed30 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74  g .** "localhost
1ed40 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  ". ^If the autho
1ed50 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65  rity is not an e
1ed60 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22  mpty string or "
1ed70 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a  localhost", an .
1ed80 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  ** error is retu
1ed90 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c  rned to the call
1eda0 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e  er. ^The fragmen
1edb0 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
1edc0 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65   URI, if .** pre
1edd0 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64  sent, is ignored
1ede0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
1edf0 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f  uses the path co
1ee00 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55  mponent of the U
1ee10 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f  RI as the name o
1ee20 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a  f the disk file.
1ee30 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e  ** which contain
1ee40 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  s the database. 
1ee50 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67  ^If the path beg
1ee60 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63  ins with a '/' c
1ee70 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68  haracter, .** th
1ee80 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72  en it is interpr
1ee90 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c  eted as an absol
1eea0 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68  ute path. ^If th
1eeb0 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20  e path does not 
1eec0 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61  begin .** with a
1eed0 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68   '/' (meaning th
1eee0 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  at the authority
1eef0 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74   section is omit
1ef00 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49  ted from the URI
1ef10 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61  ).** then the pa
1ef20 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  th is interprete
1ef30 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20  d as a relative 
1ef40 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69  path. .** ^On wi
1ef50 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74  ndows, the first
1ef60 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e   component of an
1ef70 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a   absolute path .
1ef80 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70  ** is a drive sp
1ef90 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67  ecification (e.g
1efa0 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b  . "C:")..**.** [
1efb0 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20  [core URI query 
1efc0 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20  parameters]].** 
1efd0 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  The query compon
1efe0 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79  ent of a URI may
1eff0 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74   contain paramet
1f000 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74  ers that are int
1f010 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68  erpreted.** eith
1f020 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73  er by SQLite its
1f030 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46  elf, or by a [VF
1f040 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69  S | custom VFS i
1f050 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a  mplementation]..
1f060 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70  ** SQLite interp
1f070 72 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69  rets the followi
1f080 6e 67 20 74 68 72 65 65 20 71 75 65 72 79 20 70  ng three query p
1f090 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a  arameters:.**.**
1f0a0 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
1f0b0 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65  <b>vfs</b>: ^The
1f0c0 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72   "vfs" parameter
1f0d0 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20   may be used to 
1f0e0 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65  specify the name
1f0f0 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53   of.**     a VFS
1f100 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f   object that pro
1f110 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74  vides the operat
1f120 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
1f130 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64  face that should
1f140 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20  .**     be used 
1f150 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
1f160 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64  tabase file on d
1f170 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70  isk. ^If this op
1f180 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a  tion is set to.*
1f190 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73  *     an empty s
1f1a0 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c  tring the defaul
1f1b0 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20  t VFS object is 
1f1c0 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e  used. ^Specifyin
1f1d0 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20  g an unknown.** 
1f1e0 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72      VFS is an er
1f1f0 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  ror. ^If sqlite3
1f200 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
1f210 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f  ed and the vfs o
1f220 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
1f230 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68  present, then th
1f240 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20  e VFS specified 
1f250 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61  by the option ta
1f260 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f  kes precedence o
1f270 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76  ver.**     the v
1f280 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
1f290 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1f2a0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
1f2b0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
1f2c0 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f    <li> <b>mode</
1f2d0 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70  b>: ^(The mode p
1f2e0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
1f2f0 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72  set to either "r
1f300 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20  o", "rw",.**    
1f310 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f   "rwc", or "memo
1f320 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20  ry". Attempting 
1f330 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79  to set it to any
1f340 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a   other value is.
1f350 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29  **     an error)
1f360 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22  ^. .**     ^If "
1f370 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64  ro" is specified
1f380 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
1f390 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
1f3a0 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20  r read-only .** 
1f3b0 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74      access, just
1f3c0 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49   as if the [SQLI
1f3d0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
1f3e0 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20  ] flag had been 
1f3f0 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20  set in the .**  
1f400 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e     third argumen
1f410 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 65  t to sqlite3_pre
1f420 70 61 72 65 5f 76 32 28 29 2e 20 5e 49 66 20 74  pare_v2(). ^If t
1f430 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
1f440 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20  s set to .**    
1f450 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20   "rw", then the 
1f460 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1f470 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74  ed for read-writ
1f480 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74  e (but not creat
1f490 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  e) .**     acces
1f4a0 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f  s, as if SQLITE_
1f4b0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28  OPEN_READWRITE (
1f4c0 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f  but not SQLITE_O
1f4d0 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20  PEN_CREATE) had 
1f4e0 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74  .**     been set
1f4f0 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69  . ^Value "rwc" i
1f500 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
1f510 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a  setting both .**
1f520 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
1f530 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53  _READWRITE and S
1f540 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1f550 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  E.  ^If the mode
1f560 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
1f570 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79    set to "memory
1f580 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69  " then a pure [i
1f590 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
1f5a0 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65  e] that never re
1f5b0 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72  ads.**     or wr
1f5c0 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69  ites from disk i
1f5d0 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61  s used. ^It is a
1f5e0 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69  n error to speci
1f5f0 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a  fy a value for.*
1f600 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70  *     the mode p
1f610 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73  arameter that is
1f620 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76   less restrictiv
1f630 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63  e than that spec
1f640 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
1f650 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64  the flags passed
1f660 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61   in the third pa
1f670 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1f680 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
1f690 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61  .**   <li> <b>ca
1f6a0 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61  che</b>: ^The ca
1f6b0 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  che parameter ma
1f6c0 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
1f6d0 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a  er "shared" or.*
1f6e0 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e  *     "private".
1f6f0 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20   ^Setting it to 
1f700 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69  "shared" is equi
1f710 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
1f720 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c  g the.**     SQL
1f730 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
1f740 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20  ACHE bit in the 
1f750 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70  flags argument p
1f760 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  assed to.**     
1f770 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1f780 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20  ). ^Setting the 
1f790 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
1f7a0 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20  to "private" is 
1f7b0 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65  .**     equivale
1f7c0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
1f7d0 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52  e SQLITE_OPEN_PR
1f7e0 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a  IVATECACHE bit..
1f7f0 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74  **     ^If sqlit
1f800 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
1f810 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61  used and the "ca
1f820 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69  che" parameter i
1f830 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20  s present in.** 
1f840 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61      a URI filena
1f850 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76  me, its value ov
1f860 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61  errides any beha
1f870 76 69 6f 75 72 20 72 65 71 75 65 73 74 65 64 20  viour requested 
1f880 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20  by setting.**   
1f890 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52    SQLITE_OPEN_PR
1f8a0 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51  IVATECACHE or SQ
1f8b0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
1f8c0 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c  CACHE flag..** <
1f8d0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63  /ul>.**.** ^Spec
1f8e0 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
1f8f0 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  n parameter in t
1f900 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
1f910 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e  nt of a URI is n
1f920 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20  ot an.** error. 
1f930 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
1f940 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
1f950 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69   understand addi
1f960 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20  tional query.** 
1f970 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65  parameters.  See
1f980 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74   "[query paramet
1f990 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c  ers with special
1f9a0 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69   meaning to SQLi
1f9b0 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69  te]" for.** addi
1f9c0 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
1f9d0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  on..**.** [[URI 
1f9e0 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
1f9f0 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65  s]] <h3>URI file
1fa00 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68  name examples</h
1fa10 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20  3>.**.** <table 
1fa20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e  border="1" align
1fa30 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64  =center cellpadd
1fa40 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  ing=5>.** <tr><t
1fa50 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  h> URI filenames
1fa60 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a   <th> Results.**
1fa70 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
1fa80 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
1fa90 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
1faa0 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
1fab0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
1fac0 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74  directory..** <t
1fad0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
1fae0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62  e/fred/data.db<b
1faf0 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  r>.**          f
1fb00 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64  ile:///home/fred
1fb10 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a  /data.db <br> .*
1fb20 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
1fb30 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65  //localhost/home
1fb40 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
1fb50 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  r> <td> .**     
1fb60 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61       Open the da
1fb70 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f  tabase file "/ho
1fb80 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
1fb90 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
1fba0 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f  le://darkstar/ho
1fbb0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
1fbc0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
1fbd0 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72    An error. "dar
1fbe0 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20  kstar" is not a 
1fbf0 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f  recognized autho
1fc00 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  rity..** <tr><td
1fc10 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70   style="white-sp
1fc20 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a  ace:nowrap"> .**
1fc30 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
1fc40 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32  //C:/Documents%2
1fc50 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f  0and%20Settings/
1fc60 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74  fred/Desktop/dat
1fc70 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e  a.db.**     <td>
1fc80 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f   Windows only: O
1fc90 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
1fca0 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73  ta.db" on fred's
1fcb0 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76   desktop on driv
1fcc0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a  e.**          C:
1fcd0 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
1fce0 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20  %20 escaping in 
1fcf0 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20  this example is 
1fd00 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a  not strictly .**
1fd10 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73            necess
1fd20 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72  ary - space char
1fd30 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73  acters can be us
1fd40 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20  ed literally.** 
1fd50 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20           in URI 
1fd60 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74  filenames..** <t
1fd70 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
1fd80 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68  .db?mode=ro&cach
1fd90 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a  e=private <td> .
1fda0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
1fdb0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
1fdc0 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
1fdd0 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61  irectory for rea
1fde0 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a  d-only access..*
1fdf0 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72  *          Regar
1fe00 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
1fe10 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63   or not shared-c
1fe20 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61  ache mode is ena
1fe30 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  bled by.**      
1fe40 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65      default, use
1fe50 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65   a private cache
1fe60 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
1fe70 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
1fe80 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e  ta.db?vfs=unix-n
1fe90 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20  olock <td>.**   
1fea0 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
1feb0 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
1fec0 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73  a.db". Use the s
1fed0 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78  pecial VFS "unix
1fee0 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72  -nolock"..** <tr
1fef0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
1ff00 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79  db?mode=readonly
1ff10 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
1ff20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65     An error. "re
1ff30 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61  adonly" is not a
1ff40 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f   valid option fo
1ff50 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72  r the "mode" par
1ff60 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62  ameter..** </tab
1ff70 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68  le>.**.** ^URI h
1ff80 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
1ff90 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48  e sequences (%HH
1ffa0 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  ) are supported 
1ffb0 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20  within the path 
1ffc0 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d  and.** query com
1ffd0 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49  ponents of a URI
1ffe0 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20  . A hexadecimal 
1fff0 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20  escape sequence 
20000 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a  consists of a.**
20010 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20   percent sign - 
20020 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62  "%" - followed b
20030 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65  y exactly two he
20040 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73  xadecimal digits
20050 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20   .** specifying 
20060 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20  an octet value. 
20070 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68  ^Before the path
20080 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e   or query compon
20090 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49  ents of a.** URI
200a0 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e   filename are in
200b0 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20  terpreted, they 
200c0 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  are encoded usin
200d0 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20  g UTF-8 and all 
200e0 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20  .** hexadecimal 
200f0 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
20100 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73   replaced by a s
20110 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61  ingle byte conta
20120 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72  ining the.** cor
20130 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74  responding octet
20140 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73  . If this proces
20150 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69  s generates an i
20160 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63  nvalid UTF-8 enc
20170 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65  oding,.** the re
20180 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
20190 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  ned..**.** <b>No
201a0 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
201b0 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
201c0 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
201d0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
201e0 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69  ument.** of sqli
201f0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
20200 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
20210 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
20220 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
20230 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
20240 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
20250 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
20260 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
20270 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
20280 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
20290 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
202a0 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
202b0 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  m into.** sqlite
202c0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
202d0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
202e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  /.int sqlite3_op
202f0 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
20300 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
20310 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
20320 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
20330 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
20340 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
20350 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
20360 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
20370 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e  e3_open16(.  con
20380 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
20390 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
203a0 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31   filename (UTF-1
203b0 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  6) */.  sqlite3 
203c0 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
203d0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
203e0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
203f0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
20400 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
20410 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
20420 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
20430 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
20440 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
20450 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
20460 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
20470 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
20480 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
20490 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
204a0 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
204b0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
204c0 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
204d0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
204e0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56  PI3REF: Obtain V
204f0 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61  alues For URI Pa
20500 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54  rameters.**.** T
20510 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79  hese are utility
20520 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75   routines, usefu
20530 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65  l to VFS impleme
20540 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63  ntations, that c
20550 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69  heck.** to see i
20560 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  f a database fil
20570 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74  e was a URI that
20580 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65   contained a spe
20590 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20  cific query .** 
205a0 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69  parameter, and i
205b0 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65  f so obtains the
205c0 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71   value of that q
205d0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a  uery parameter..
205e0 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68  **.** If F is th
205f0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  e database filen
20600 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73  ame pointer pass
20610 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65  ed into the xOpe
20620 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a  n() method of .*
20630 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  * a VFS implemen
20640 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20  tation when the 
20650 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
20660 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f  to xOpen() has o
20670 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f  ne or .** more o
20680 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
20690 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49  EN_URI] or [SQLI
206a0 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
206b0 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a   bits set and.**
206c0 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f   P is the name o
206d0 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61  f the query para
206e0 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73  meter, then.** s
206f0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
20700 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
20710 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
20720 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65  he P.** paramete
20730 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f  r if it exists o
20740 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
20750 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61   if P does not a
20760 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71  ppear as a .** q
20770 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f  uery parameter o
20780 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20  n F.  If P is a 
20790 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
207a0 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65  of F.** has no e
207b0 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74  xplicit value, t
207c0 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
207d0 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
207e0 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e  eturns.** a poin
207f0 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  ter to an empty 
20800 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
20810 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
20820 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
20830 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61  tine assumes tha
20840 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  t P is a boolean
20850 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e  .** parameter an
20860 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  d returns true (
20870 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20  1) or false (0) 
20880 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65  according to the
20890 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20   value.** of P. 
208a0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
208b0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
208c0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
208d0 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a  true (1) if the.
208e0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72  ** value of quer
208f0 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
20900 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22   one of "yes", "
20910 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69  true", or "on" i
20920 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72  n any.** case or
20930 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
20940 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d  gins with a non-
20950 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68  zero number.  Th
20960 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  e .** sqlite3_ur
20970 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
20980 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
20990 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74  s false (0) if t
209a0 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71  he value of.** q
209b0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
209c0 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c   is one of "no",
209d0 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66   "false", or "of
209e0 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f  f" in any case o
209f0 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75  r.** if the valu
20a00 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  e begins with a 
20a10 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49  numeric zero.  I
20a20 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65  f P is not a que
20a30 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  ry.** parameter 
20a40 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76  on F or if the v
20a50 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65  alue of P is doe
20a60 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20  s not match any 
20a70 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c  of the.** above,
20a80 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
20a90 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
20aa0 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e   returns (B!=0).
20ab0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
20ac0 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50  e3_uri_int64(F,P
20ad0 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76  ,D) routine conv
20ae0 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f  erts the value o
20af0 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34  f P into a.** 64
20b00 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
20b10 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ger and returns 
20b20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72  that integer, or
20b30 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74   D if P does not
20b40 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74  .** exist.  If t
20b50 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73  he value of P is
20b60 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
20b70 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72   than an integer
20b80 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69  , then.** zero i
20b90 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a  s returned..** .
20ba0 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c  ** If F is a NUL
20bb0 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
20bc0 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
20bd0 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
20be0 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73  ns NULL and.** s
20bf0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
20c00 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e  an(F,P,B) return
20c10 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f  s B.  If F is no
20c20 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  t a NULL pointer
20c30 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61   and.** is not a
20c40 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70   database file p
20c50 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20  athname pointer 
20c60 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73  that SQLite pass
20c70 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65  ed into the xOpe
20c80 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c  n.** VFS method,
20c90 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
20ca0 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  or of this routi
20cb0 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  ne is undefined 
20cc0 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20  and probably.** 
20cd0 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a  undesirable..*/.
20ce0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
20cf0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
20d00 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  r(const char *zF
20d10 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63  ilename, const c
20d20 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e  har *zParam);.in
20d30 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  t sqlite3_uri_bo
20d40 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72  olean(const char
20d50 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63   *zFile, const c
20d60 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74  har *zParam, int
20d70 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69   bDefault);.sqli
20d80 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
20d90 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73  3_uri_int64(cons
20da0 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63  t char*, const c
20db0 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  har*, sqlite3_in
20dc0 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t64);.../*.** CA
20dd0 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
20de0 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
20df0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
20e00 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e  te3_errcode() in
20e10 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
20e20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73  the numeric [res
20e30 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ult code] or.** 
20e40 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
20e50 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d   code] for the m
20e60 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65  ost recent faile
20e70 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20  d sqlite3_* API 
20e80 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74  call.** associat
20e90 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ed with a [datab
20ea0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
20eb0 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20   If a prior API 
20ec0 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62  call failed.** b
20ed0 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  ut the most rece
20ee0 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63  nt API call succ
20ef0 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72  eeded, the retur
20f00 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20  n value from.** 
20f10 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
20f20 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
20f30 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
20f40 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
20f50 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
20f60 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74   the same except
20f70 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20   that it always 
20f80 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20  returns the .** 
20f90 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
20fa0 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e   code] even when
20fb0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
20fc0 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69   codes are.** di
20fd0 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  sabled..**.** ^T
20fe0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
20ff0 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
21000 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
21010 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  n English-langua
21020 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
21030 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
21040 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
21050 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72  TF-8 or UTF-16 r
21060 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
21070 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
21080 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
21090 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
210a0 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e  aged internally.
210b0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
210c0 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
210d0 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74  d to worry about
210e0 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73   freeing the res
210f0 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ult..** However,
21100 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e   the error strin
21110 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77  g might be overw
21120 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f  ritten or deallo
21130 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73  cated by.** subs
21140 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
21150 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
21160 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73  erface functions
21170 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  .)^.**.** When t
21180 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
21190 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69  hreading mode] i
211a0 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67  s in use, it mig
211b0 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73  ht be the.** cas
211c0 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20  e that a second 
211d0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20  error occurs on 
211e0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
211f0 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  d in between.** 
21200 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20  the time of the 
21210 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20  first error and 
21220 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73  the call to thes
21230 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  e interfaces..**
21240 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65   When that happe
21250 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ns, the second e
21260 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70  rror will be rep
21270 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73  orted since thes
21280 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
21290 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68  always report th
212a0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65  e most recent re
212b0 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a  sult.  To avoid.
212c0 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68  ** this, each th
212d0 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20  read can obtain 
212e0 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66  exclusive use of
212f0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
21300 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
21310 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  by invoking [sql
21320 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
21330 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
21340 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20  tex](D)) before 
21350 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20  beginning.** to 
21360 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69  use D and invoki
21370 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
21380 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65  x_leave]([sqlite
21390 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
213a0 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c  after.** all cal
213b0 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66  ls to the interf
213c0 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65  aces listed here
213d0 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a   are completed..
213e0 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  **.** If an inte
213f0 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
21400 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20   SQLITE_MISUSE, 
21410 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69  that means the i
21420 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20  nterface.** was 
21430 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63  invoked incorrec
21440 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69  tly by the appli
21450 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74  cation.  In that
21460 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72   case, the.** er
21470 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
21480 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20  sage may or may 
21490 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69  not be set..*/.i
214a0 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  nt sqlite3_errco
214b0 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
214c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
214d0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71  ended_errcode(sq
214e0 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73  lite3 *db);.cons
214f0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
21500 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29  errmsg(sqlite3*)
21510 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
21520 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
21530 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
21540 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53   CAPI3REF: SQL S
21550 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
21560 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
21570 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21580 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
21590 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
215a0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
215b0 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
215c0 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
215d0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54   statement..** T
215e0 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61  his object is va
215f0 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73  riously known as
21600 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61   a "prepared sta
21610 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20  tement" or a.** 
21620 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74  "compiled SQL st
21630 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70  atement" or simp
21640 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65  ly as a "stateme
21650 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  nt"..**.** The l
21660 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65  ife of a stateme
21670 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73  nt object goes s
21680 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68  omething like th
21690 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
216a0 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
216b0 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
216c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
216d0 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74  v2()] or a relat
216e0 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74  ed.**      funct
216f0 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ion..** <li> Bin
21700 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73  d values to [hos
21710 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73  t parameters] us
21720 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
21730 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
21740 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
21750 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
21760 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
21770 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
21780 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
21790 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
217a0 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  e statement usin
217b0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
217c0 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
217d0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
217e0 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
217f0 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
21800 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
21810 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
21820 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
21830 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
21840 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  .**.** Refer to 
21850 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e  documentation on
21860 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68   individual meth
21870 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64  ods above for ad
21880 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
21890 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  rmation..*/.type
218a0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
218b0 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
218c0 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
218d0 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
218e0 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  Limits.**.** ^(T
218f0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
21900 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66  lows the size of
21910 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75   various constru
21920 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65  cts to be limite
21930 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63  d.** on a connec
21940 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69  tion by connecti
21950 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66  on basis.  The f
21960 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
21970 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  s the.** [databa
21980 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
21990 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f  hose limit is to
219a0 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69   be set or queri
219b0 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ed.  The.** seco
219c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
219d0 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69  one of the [limi
219e0 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68  t categories] th
219f0 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63  at define a.** c
21a00 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63  lass of construc
21a10 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69  ts to be size li
21a20 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72  mited.  The thir
21a30 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
21a40 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20  he.** new limit 
21a50 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75  for that constru
21a60 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ct.)^.**.** ^If 
21a70 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73  the new limit is
21a80 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
21a90 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73  er, the limit is
21aa0 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e   unchanged..** ^
21ab0 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20  (For each limit 
21ac0 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f  category SQLITE_
21ad0 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  LIMIT_<i>NAME</i
21ae0 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a  > there is a .**
21af0 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20   [limits | hard 
21b00 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20  upper bound].** 
21b10 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
21b20 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72  ime by a C prepr
21b30 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61  ocessor macro ca
21b40 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  lled.** [limits 
21b50 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e  | SQLITE_MAX_<i>
21b60 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54  NAME</i>]..** (T
21b70 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
21b80 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
21b90 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
21ba0 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20  )^.** ^Attempts 
21bb0 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
21bc0 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
21bd0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
21be0 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
21bf0 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
21c00 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
21c10 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c  ..**.** ^Regardl
21c20 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
21c30 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20  r not the limit 
21c40 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65  was changed, the
21c50 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69   .** [sqlite3_li
21c60 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  mit()] interface
21c70 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69   returns the pri
21c80 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  or value of the 
21c90 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65  limit..** ^Hence
21ca0 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75  , to find the cu
21cb0 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61  rrent value of a
21cc0 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63   limit without c
21cd0 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73  hanging it,.** s
21ce0 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69  imply invoke thi
21cf0 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68  s interface with
21d00 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
21d10 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a  eter set to -1..
21d20 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c  **.** Run-time l
21d30 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64  imits are intend
21d40 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70  ed for use in ap
21d50 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
21d60 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74  manage.** both t
21d70 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61  heir own interna
21d80 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  l database and a
21d90 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68  lso databases th
21da0 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65  at are controlle
21db0 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65  d.** by untruste
21dc0 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  d external sourc
21dd0 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  es.  An example 
21de0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68  application migh
21df0 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72  t be a.** web br
21e00 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
21e10 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
21e20 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
21e30 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
21e40 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
21e50 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
21e60 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
21e70 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
21e80 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
21e90 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
21ea0 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
21eb0 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
21ec0 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
21ed0 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
21ee0 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
21ef0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
21f00 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
21f10 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
21f20 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
21f30 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
21f40 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
21f50 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
21f60 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
21f70 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
21f80 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
21f90 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
21fa0 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
21fb0 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
21fc0 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
21fd0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
21fe0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
21ff0 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
22000 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
22010 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
22020 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
22030 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
22040 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c  * New run-time l
22050 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20  imit categories 
22060 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
22070 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
22080 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
22090 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
220a0 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
220b0 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
220c0 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
220d0 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a  imit Categories.
220e0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
220f0 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a  mit category} {*
22100 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
22110 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
22120 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
22130 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
22140 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
22150 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
22160 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
22170 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
22180 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
22190 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
221a0 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
221b0 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
221c0 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
221d0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
221e0 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
221f0 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
22200 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
22210 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
22220 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
22230 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
22240 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
22250 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
22260 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
22270 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
22280 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
22290 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64  ow, in bytes.<dd
222a0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
222b0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
222c0 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
222d0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
222e0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
222f0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
22300 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
22310 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73  tement, in bytes
22320 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
22330 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
22340 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LUMN]] ^(<dt>SQL
22350 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
22360 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
22370 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
22380 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
22390 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e  table definition
223a0 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65   or in the.** re
223b0 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
223c0 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61  ELECT] or the ma
223d0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
223e0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
223f0 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
22400 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
22410 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
22420 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
22430 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
22440 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
22450 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
22460 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
22470 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
22480 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
22490 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
224a0 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
224b0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
224c0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
224d0 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  CT]] ^(<dt>SQLIT
224e0 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
224f0 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
22500 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
22510 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
22520 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
22530 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
22540 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
22550 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
22560 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  _OP]] ^(<dt>SQLI
22570 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
22580 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
22590 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
225a0 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20  of instructions 
225b0 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
225c0 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20  hine program.** 
225d0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
225e0 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t an SQL stateme
225f0 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20  nt.  This limit 
22600 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
22610 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68  .** enforced, th
22620 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20  ough that might 
22630 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65  be added in some
22640 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
22650 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64  of.** SQLite.</d
22660 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
22670 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
22680 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53  ON_ARG]] ^(<dt>S
22690 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
226a0 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a  TION_ARG</dt>.**
226b0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
226c0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
226d0 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69  ents on a functi
226e0 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
226f0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
22700 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74  ATTACHED]] ^(<dt
22710 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
22720 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
22730 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
22740 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48  umber of [ATTACH
22750 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61   | attached data
22760 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  bases].)^</dd>.*
22770 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
22780 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
22790 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c  _LENGTH]].** ^(<
227a0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
227b0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
227c0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
227d0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
227e0 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
227f0 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
22800 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b  e [LIKE] or.** [
22810 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e  GLOB] operators.
22820 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
22830 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
22840 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a  IABLE_NUMBER]].*
22850 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
22860 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
22870 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
22880 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64  >The maximum ind
22890 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79  ex number of any
228a0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20   [parameter] in 
228b0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
228c0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
228d0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
228e0 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
228f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
22900 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
22910 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
22920 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
22930 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
22940 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  s.</dd>)^.** </d
22950 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
22960 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
22970 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
22980 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
22990 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
229a0 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
229b0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
229c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
229d0 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
229e0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
229f0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
22a00 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
22a10 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
22a20 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
22a30 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
22a40 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
22a50 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
22a60 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
22a70 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
22a80 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
22a90 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
22aa0 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
22ab0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
22ac0 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
22ad0 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
22ae0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
22af0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
22b00 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
22b10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
22b20 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
22b30 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
22b40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
22b50 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
22b60 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
22b70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22b80 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
22b90 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
22ba0 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
22bb0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
22bc0 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
22bd0 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
22be0 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
22bf0 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
22c00 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
22c10 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
22c20 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
22c30 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
22c40 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
22c50 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
22c60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
22c70 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
22c80 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
22c90 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
22ca0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
22cb0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
22cc0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
22cd0 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
22ce0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
22cf0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
22d00 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
22d10 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
22d20 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
22d30 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
22d40 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
22d50 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
22d60 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
22d70 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
22d80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
22d90 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
22da0 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
22db0 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
22dc0 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
22dd0 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
22de0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
22df0 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
22e00 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
22e10 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
22e20 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a  t is less than z
22e30 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
22e40 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
22e50 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74  .** first zero t
22e60 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e  erminator. ^If n
22e70 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
22e80 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
22e90 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
22ea0 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73  number of  bytes
22eb0 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
22ec0 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73    ^When nByte is
22ed0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
22ee0 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e  he.** zSql strin
22ef0 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72  g ends at either
22f00 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30   the first '\000
22f10 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68  ' or '\u0000' ch
22f20 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68  aracter or.** th
22f30 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
22f40 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
22f50 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63   first. If the c
22f60 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74  aller knows.** t
22f70 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
22f80 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
22f90 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20  erminated, then 
22fa0 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
22fb0 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  .** performance 
22fc0 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20  advantage to be 
22fd0 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e  gained by passin
22fe0 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
22ff0 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
23000 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d  equal to the num
23010 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
23020 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
23030 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
23040 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
23050 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73  minator bytes as
23060 20 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69   this saves SQLi
23070 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74  te from having t
23080 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79  o.** make a copy
23090 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   of the input st
230a0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ring..**.** ^If 
230b0 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
230c0 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
230d0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
230e0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
230f0 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
23100 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
23110 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
23120 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
23130 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
23140 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
23150 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
23160 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
23170 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
23180 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
23190 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
231a0 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
231b0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
231c0 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
231d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
231e0 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
231f0 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
23200 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
23210 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
23220 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
23230 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
23240 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
23250 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
23260 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
23270 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
23280 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
23290 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
232a0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
232b0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
232c0 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
232d0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
232e0 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
232f0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
23300 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
23310 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
23320 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
23330 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
23340 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
23350 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
23360 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
23370 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
23380 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
23390 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
233a0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
233b0 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
233c0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
233d0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
233e0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
233f0 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
23400 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
23410 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
23420 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
23430 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
23440 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
23450 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
23460 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
23470 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
23480 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
23490 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
234a0 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
234b0 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
234c0 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
234d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
234e0 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
234f0 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
23500 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
23510 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
23520 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
23530 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
23540 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
23550 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
23560 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
23570 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
23580 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
23590 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
235a0 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
235b0 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
235c0 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
235d0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
235e0 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
235f0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
23600 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
23610 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
23620 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
23630 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
23640 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
23650 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
23660 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  n..** </li>.**.*
23670 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20  * <li>.** ^When 
23680 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
23690 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
236a0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
236b0 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
236c0 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
236d0 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
236e0 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e  error codes].  ^
236f0 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
23700 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
23710 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
23720 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
23730 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
23740 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
23750 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74  lt code.** and t
23760 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
23770 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
23780 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
23790 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
237a0 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  t()].** in order
237b0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
237c0 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
237d0 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
237e0 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
237f0 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
23800 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
23810 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
23820 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
23830 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
23840 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
23850 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  li>.** ^If the s
23860 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f  pecific value bo
23870 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  und to [paramete
23880 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
23890 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57  er] in the .** W
238a0 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
238b0 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
238c0 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
238d0 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
238e0 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ment,.** then th
238f0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  e statement will
23900 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
23910 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73  y recompiled, as
23920 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
23930 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20  en .** a schema 
23940 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66  change, on the f
23950 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73  irst  [sqlite3_s
23960 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
23970 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
23980 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
23990 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
239a0 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61  bindings] of tha
239b0 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  t [parameter]. .
239c0 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63  ** ^The specific
239d0 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d   value of WHERE-
239e0 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65  clause [paramete
239f0 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  r] might influen
23a00 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63  ce the .** choic
23a10 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
23a20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
23a30 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e   is the left-han
23a40 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b  d side of a [LIK
23a50 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20  E].** or [GLOB] 
23a60 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74  operator or if t
23a70 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
23a80 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69  compared to an i
23a90 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  ndexed column.**
23aa0 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45   and the [SQLITE
23ab0 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63  _ENABLE_STAT3] c
23ac0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
23ad0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
23ae0 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a  * the .** </li>.
23af0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20  ** </ol>.*/.int 
23b00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
23b10 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
23b20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
23b30 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
23b40 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
23b50 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
23b60 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
23b70 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
23b80 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
23b90 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
23ba0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
23bb0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
23bc0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
23bd0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
23be0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
23bf0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
23c00 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
23c10 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
23c20 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
23c30 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
23c40 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
23c50 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
23c60 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
23c70 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
23c80 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
23c90 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
23ca0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
23cb0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
23cc0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
23cd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
23ce0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
23cf0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
23d00 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
23d10 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
23d20 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
23d30 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
23d40 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
23d50 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
23d60 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
23d70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
23d80 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
23d90 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
23da0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
23db0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
23dc0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
23dd0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
23de0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
23df0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
23e00 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
23e10 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
23e20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
23e30 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
23e40 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
23e50 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
23e60 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
23e70 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
23e80 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
23e90 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
23ea0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
23eb0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
23ec0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
23ed0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
23ee0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
23ef0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
23f00 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
23f10 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
23f20 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
23f30 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
23f40 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
23f50 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
23f60 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
23f70 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
23f80 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
23f90 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
23fa0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
23fb0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
23fc0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
23fd0 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
23fe0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
23ff0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
24000 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
24010 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
24020 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
24030 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a  Statement SQL.**
24040 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
24050 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
24060 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61  to retrieve a sa
24070 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ved copy of the 
24080 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20  original.** SQL 
24090 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65  text used to cre
240a0 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ate a [prepared 
240b0 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68  statement] if th
240c0 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  at statement was
240d0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  .** compiled usi
240e0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
240f0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
24100 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
24110 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f  pare16_v2()]..*/
24120 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
24130 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33  ite3_sql(sqlite3
24140 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
24150 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24160 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
24170 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72  SQL Statement Wr
24180 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73  ites The Databas
24190 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
241a0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
241b0 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20  ly(X) interface 
241c0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
241d0 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e  n-zero) if.** an
241e0 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70  d only if the [p
241f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24200 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69  t] X makes no di
24210 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a  rect changes to.
24220 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
24230 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
24240 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ile..**.** Note 
24250 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f  that [applicatio
24260 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
24270 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b  nctions] or.** [
24280 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20  virtual tables] 
24290 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65  might change the
242a0 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65   database indire
242b0 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65  ctly as a side e
242c0 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f  ffect.  .** ^(Fo
242d0 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e  r example, if an
242e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
242f0 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20  ines a function 
24300 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a  "eval()" that .*
24310 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33  * calls [sqlite3
24320 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74  _exec()], then t
24330 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
24340 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64   statement would
24350 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64  .** change the d
24360 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72  atabase file thr
24370 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74  ough side-effect
24380 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
24390 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
243a0 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45   SELECT eval('DE
243b0 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46  LETE FROM t1') F
243c0 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65  ROM t2;.** </pre
243d0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
243e0 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65  *.** But because
243f0 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
24400 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
24410 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
24420 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72  base file.** dir
24430 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73  ectly, sqlite3_s
24440 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77  tmt_readonly() w
24450 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72  ould still retur
24460 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  n true.)^.**.** 
24470 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e  ^Transaction con
24480 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20  trol statements 
24490 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c  such as [BEGIN],
244a0 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c   [COMMIT], [ROLL
244b0 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50  BACK],.** [SAVEP
244c0 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45  OINT], and [RELE
244d0 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74  ASE] cause sqlit
244e0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
244f0 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
24500 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  e,.** since the 
24510 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73  statements thems
24520 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74  elves do not act
24530 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65  ually modify the
24540 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a   database but.**
24550 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e   rather they con
24560 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20  trol the timing 
24570 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74  of when other st
24580 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20  atements modify 
24590 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  the .** database
245a0 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d  .  ^The [ATTACH]
245b0 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74   and [DETACH] st
245c0 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61  atements also ca
245d0 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  use.** sqlite3_s
245e0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
245f0 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69  o return true si
24600 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65  nce, while those
24610 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63   statements.** c
24620 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67  hange the config
24630 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74  uration of a dat
24640 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24650 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61  , they do not ma
24660 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ke .** changes t
24670 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  o the content of
24680 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
24690 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a  les on disk..*/.
246a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
246b0 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65  _readonly(sqlite
246c0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
246d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
246e0 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20   Determine If A 
246f0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
24700 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65  nt Has Been Rese
24710 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
24720 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
24730 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
24740 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
24750 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70  ro) if the.** [p
24760 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24770 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74  t] S has been st
24780 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f  epped at least o
24790 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  nce using .** [s
247a0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
247b0 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20  but has not run 
247c0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e  to completion an
247d0 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a  d/or has not .**
247e0 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e   been reset usin
247f0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
24800 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  (S)].  ^The sqli
24810 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
24820 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
24830 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53  turns false if S
24840 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
24850 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74  er.  If S is not
24860 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e   a .** NULL poin
24870 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ter and is not a
24880 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
24890 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  lid [prepared st
248a0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
248b0 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ct, then the beh
248c0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
248d0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
248e0 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a  undesirable..**.
248f0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
24900 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  e can be used in
24910 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71   combination [sq
24920 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
24930 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20  )].** to locate 
24940 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61  all prepared sta
24950 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
24960 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61  ed with a databa
24970 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  se .** connectio
24980 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65  n that are in ne
24990 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65  ed of being rese
249a0 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20  t.  This can be 
249b0 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61  used,.** for exa
249c0 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73  mple, in diagnos
249d0 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tic routines to 
249e0 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61  search for prepa
249f0 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  red .** statemen
24a00 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64  ts that are hold
24a10 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ing a transactio
24a20 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  n open..*/.int s
24a30 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
24a40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
24a50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24a60 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
24a70 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
24a80 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
24a90 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
24aa0 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
24ab0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
24ac0 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
24ad0 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
24ae0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
24af0 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
24b00 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
24b10 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
24b20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
24b30 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
24b40 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
24b50 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
24b60 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
24b70 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
24b80 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
24b90 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
24ba0 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
24bb0 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
24bc0 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
24bd0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
24be0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
24bf0 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
24c00 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
24c10 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
24c20 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
24c30 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
24c40 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
24c50 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
24c60 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
24c70 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
24c80 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
24c90 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
24ca0 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
24cb0 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
24cc0 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
24cd0 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
24ce0 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
24cf0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
24d00 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
24d10 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
24d20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
24d30 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65   terms "protecte
24d40 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63  d" and "unprotec
24d50 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68  ted" refer to wh
24d60 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20  ether or not.** 
24d70 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e  a mutex is held.
24d80 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75    An internal mu
24d90 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
24da0 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
24db0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
24dc0 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
24dd0 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
24de0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
24df0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
24e00 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
24e10 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
24e20 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
24e30 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
24e40 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
24e50 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
24e60 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
24e70 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
24e80 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
24e90 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
24ea0 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
24eb0 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
24ec0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
24ed0 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
24ee0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
24ef0 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
24f00 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
24f10 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
24f20 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
24f30 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
24f40 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
24f50 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
24f60 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
24f70 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
24f80 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
24f90 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
24fa0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
24fb0 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
24fc0 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
24fd0 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
24fe0 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
24ff0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
25000 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
25010 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
25020 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
25030 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
25040 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
25050 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
25060 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
25070 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
25080 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
25090 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
250a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
250b0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
250c0 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
250d0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
250e0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
250f0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
25100 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
25110 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
25120 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
25130 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
25140 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
25150 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
25160 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
25170 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
25180 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
25190 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
251a0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
251b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
251c0 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
251d0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
251e0 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
251f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
25200 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
25210 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
25220 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
25230 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
25240 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
25250 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
25260 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
25270 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
25280 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
25290 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
252a0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
252b0 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
252c0 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
252d0 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
252e0 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
252f0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
25300 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
25310 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
25320 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
25330 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
25340 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
25350 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
25360 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
25370 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
25380 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
25390 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
253a0 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
253b0 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
253c0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
253d0 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
253e0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
253f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
25400 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
25410 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
25420 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
25430 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
25440 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
25450 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
25460 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
25470 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
25480 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25490 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
254a0 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
254b0 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
254c0 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
254d0 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
254e0 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
254f0 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
25500 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
25510 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
25520 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
25530 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
25540 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53  **.** ^(In the S
25550 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
25560 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  t input to [sqli
25570 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
25580 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
25590 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
255a0 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
255b0 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
255c0 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
255d0 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
255e0 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
255f0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
25600 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
25610 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
25620 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
25630 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
25640 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
25650 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
25660 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
25670 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
25680 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
25690 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
256a0 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
256b0 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76  ifier.)^  ^The v
256c0 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a  alues of these.*
256d0 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  * parameters (al
256e0 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
256f0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
25700 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
25710 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
25720 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
25730 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
25740 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
25750 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  here..**.** ^The
25760 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
25770 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
25780 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
25790 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20   is always.** a 
257a0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
257b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
257c0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
257d0 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
257e0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
257f0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a  its variants..**
25800 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
25810 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
25820 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c  index of the SQL
25830 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
25840 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65   set..** ^The le
25850 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d  ftmost SQL param
25860 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
25870 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74  x of 1.  ^When t
25880 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a  he same named.**
25890 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
258a0 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
258b0 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
258c0 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
258d0 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
258e0 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
258f0 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
25900 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65  urrence..** ^The
25910 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
25920 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
25930 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
25940 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
25950 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
25960 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
25970 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65  f desired.  ^The
25980 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f   index.** for "?
25990 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20  NNN" parameters 
259a0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
259b0 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e  NNN..** ^The NNN
259c0 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
259d0 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
259e0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
259f0 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
25a00 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
25a10 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
25a20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
25a30 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  99)..**.** ^The 
25a40 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
25a50 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
25a60 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
25a70 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  eter..**.** ^(In
25a80 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
25a90 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
25aa0 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
25ab0 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
25ac0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
25ad0 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
25ae0 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
25af0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
25b00 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
25b10 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
25b20 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
25b30 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
25b40 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66  acters.)^.** ^If
25b50 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
25b60 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76  meter is negativ
25b70 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  e, the length of
25b80 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
25b90 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
25ba0 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
25bb0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
25bc0 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 61 20 6e  nator..** If a n
25bd0 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72  on-negative four
25be0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
25bf0 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69  provided to sqli
25c00 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a  te3_bind_text().
25c10 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
25c20 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e  nd_text16() then
25c30 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20   that parameter 
25c40 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
25c50 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65   offset.** where
25c60 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61   the NUL termina
25c70 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20  tor would occur 
25c80 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72  assuming the str
25c90 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20  ing were NUL.** 
25ca0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20  terminated.  If 
25cb0 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65  any NUL characte
25cc0 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65  rs occur at byte
25cd0 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68   offsets less th
25ce0 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  an .** the value
25cf0 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
25d00 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68  arameter then th
25d10 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
25d20 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a  ng value will.**
25d30 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65   contain embedde
25d40 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73  d NULs.  The res
25d50 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
25d60 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72  ns involving str
25d70 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62  ings.** with emb
25d80 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
25d90 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
25da0 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
25db0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
25dc0 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  nd_blob(), sqlit
25dd0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
25de0 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62  and.** sqlite3_b
25df0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20  ind_text16() is 
25e00 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65  a destructor use
25e10 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  d to dispose of 
25e20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73  the BLOB or.** s
25e30 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69  tring after SQLi
25e40 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  te has finished 
25e50 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64  with it.  ^The d
25e60 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c  estructor is cal
25e70 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73  led.** to dispos
25e80 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
25e90 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20   string even if 
25ea0 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  the call to sqli
25eb0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c  te3_bind_blob(),
25ec0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
25ed0 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69  _text(), or sqli
25ee0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
25ef0 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49  ) fails.  .** ^I
25f00 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
25f10 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
25f20 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
25f30 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
25f40 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
25f50 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
25f60 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
25f70 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
25f80 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
25f90 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
25fa0 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  freed..** ^If th
25fb0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
25fc0 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
25fd0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
25fe0 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
25ff0 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
26000 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
26010 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
26020 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
26030 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
26040 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
26050 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
26060 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
26070 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
26080 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
26090 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
260a0 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
260b0 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72   zeroes.  ^A zer
260c0 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
260d0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
260e0 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
260f0 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
26100 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20  its size) while 
26110 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63  it is being proc
26120 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c  essed..** Zerobl
26130 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
26140 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
26150 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c  ceholders for BL
26160 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e  OBs whose.** con
26170 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72  tent is later wr
26180 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  itten using.** [
26190 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
261a0 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
261b0 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
261c0 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69  es..** ^A negati
261d0 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
261e0 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
261f0 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
26200 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e  th BLOB..**.** ^
26210 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71  If any of the sq
26220 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
26230 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
26240 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
26250 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68  ointer.** for th
26260 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
26270 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61  ement] or with a
26280 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
26290 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a  ent for which.**
262a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
262b0 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
262c0 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20  d more recently 
262d0 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  than [sqlite3_re
262e0 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  set()],.** then 
262f0 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65  the call will re
26300 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  turn [SQLITE_MIS
26310 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71  USE].  If any sq
26320 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a  lite3_bind_().**
26330 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73   routine is pass
26340 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ed a [prepared s
26350 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
26360 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
26370 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  d, the.** result
26380 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
26390 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66  d probably harmf
263a0 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69  ul..**.** ^Bindi
263b0 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
263c0 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
263d0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
263e0 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e  tine..** ^Unboun
263f0 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
26400 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
26410 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
26420 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20   sqlite3_bind_* 
26430 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
26440 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
26450 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20  uccess or an.** 
26460 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
26470 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
26480 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ong..** ^[SQLITE
26490 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
264a0 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
264b0 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
264c0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
264d0 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
264e0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
264f0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
26500 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
26510 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
26520 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
26530 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
26540 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
26550 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
26560 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
26570 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
26580 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
26590 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
265a0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
265b0 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
265c0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
265d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
265e0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
265f0 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
26600 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
26610 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
26620 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
26630 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
26640 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
26650 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
26660 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
26670 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
26680 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
26690 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
266a0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
266b0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
266c0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
266d0 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
266e0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
266f0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
26700 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
26710 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
26720 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
26730 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
26740 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
26750 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
26760 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
26770 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
26780 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
26790 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
267a0 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
267b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
267c0 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
267d0 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  meters.**.** ^Th
267e0 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
267f0 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
26800 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
26810 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
26820 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
26830 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
26840 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
26850 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
26860 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
26870 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
26880 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
26890 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
268a0 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
268b0 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
268c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
268d0 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
268e0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
268f0 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
26900 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
26910 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
26920 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
26930 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
26940 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
26950 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
26960 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
26970 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
26980 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
26990 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
269a0 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
269b0 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
269c0 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
269d0 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
269e0 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
269f0 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
26a00 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
26a10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
26a20 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
26a30 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
26a40 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
26a50 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
26a60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
26a70 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
26a80 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
26a90 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
26aa0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
26ab0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
26ac0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
26ad0 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
26ae0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
26af0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
26b00 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
26b10 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
26b20 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
26b30 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
26b40 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
26b50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
26b60 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
26b70 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
26b80 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
26b90 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
26ba0 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
26bb0 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
26bc0 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
26bd0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
26be0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
26bf0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
26c00 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
26c10 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
26c20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
26c30 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
26c40 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
26c50 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
26c60 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
26c70 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
26c80 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
26c90 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
26ca0 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
26cb0 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
26cc0 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
26cd0 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
26ce0 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
26cf0 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
26d00 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
26d10 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
26d20 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
26d30 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
26d40 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
26d50 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
26d60 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
26d70 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
26d80 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
26d90 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
26da0 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
26db0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
26dc0 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
26dd0 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
26de0 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
26df0 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
26e00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
26e10 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
26e20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
26e30 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
26e40 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
26e50 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
26e60 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
26e70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
26e80 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
26e90 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
26ea0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
26eb0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  ndex()]..*/.cons
26ec0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
26ed0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
26ee0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
26ef0 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
26f00 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
26f10 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
26f20 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
26f30 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
26f40 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
26f50 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
26f60 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
26f70 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
26f80 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
26f90 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
26fa0 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
26fb0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
26fc0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
26fd0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
26fe0 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
26ff0 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
27000 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
27010 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
27020 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
27030 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
27040 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
27050 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
27060 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
27070 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
27080 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
27090 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
270a0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
270b0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
270c0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
270d0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
270e0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
270f0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
27100 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
27110 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
27120 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
27130 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
27140 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
27150 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
27160 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
27170 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
27180 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
27190 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
271a0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
271b0 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
271c0 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
271d0 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
271e0 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
271f0 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
27200 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
27210 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
27220 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
27230 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
27240 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
27250 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
27260 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
27270 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
27280 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
27290 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
272a0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
272b0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
272c0 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
272d0 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52  ult Set.**.** ^R
272e0 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
272f0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
27300 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
27310 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
27320 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
27330 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75  ment]. ^This rou
27340 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
27350 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
27360 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  L.** statement t
27370 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
27380 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78  urn data (for ex
27390 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
273a0 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
273b0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  so: [sqlite3_dat
273c0 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  a_count()].*/.in
273d0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
273e0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
273f0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
27400 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
27410 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
27420 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
27430 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
27440 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
27450 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
27460 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
27470 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
27480 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
27490 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  CT] statement.  
274a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
274b0 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
274c0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
274d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
274e0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
274f0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
27500 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
27510 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
27520 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
27530 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
27540 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
27550 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ng.  ^The first 
27560 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
27570 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
27580 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
27590 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
275a0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
275b0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
275c0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
275d0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
275e0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
275f0 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
27600 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  0..**.** ^The re
27610 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
27620 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
27630 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
27640 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27650 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
27660 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
27670 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
27680 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
27690 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
276a0 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
276b0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
276c0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
276d0 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
276e0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
276f0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
27700 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
27710 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
27720 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
27730 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
27740 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
27750 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c  n..**.** ^If sql
27760 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
27770 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
27780 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
27790 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
277a0 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
277b0 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
277c0 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
277d0 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
277e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
277f0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
27800 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72  ^The name of a r
27810 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
27820 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
27830 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
27840 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
27850 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
27860 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
27870 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
27880 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
27890 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
278a0 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
278b0 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
278c0 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
278d0 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
278e0 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
278f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
27900 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
27910 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
27920 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  nt N);.const voi
27930 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
27940 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
27950 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
27960 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27970 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20   Source Of Data 
27980 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  In A Query Resul
27990 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
279a0 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
279b0 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
279c0 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73  mine the databas
279d0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a  e, table, and.**
279e0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
279f0 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e  at is the origin
27a00 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72   of a particular
27a10 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
27a20 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74  n.** [SELECT] st
27a30 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  atement..** ^The
27a40 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
27a50 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
27a60 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
27a70 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
27a80 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72  ither a UTF-8 or
27a90 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
27aa0 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f   ^The _database_
27ab0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
27ac0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
27ad0 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
27ae0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
27af0 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
27b00 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
27b10 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
27b20 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
27b30 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72   name..** ^The r
27b40 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
27b50 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
27b60 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
27b70 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
27b80 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
27b90 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
27ba0 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
27bb0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
27bc0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
27bd0 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
27be0 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
27bf0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
27c00 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
27c10 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
27c20 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
27c30 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
27c40 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
27c50 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
27c60 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  g..**.** ^The na
27c70 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
27c80 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
27c90 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
27ca0 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
27cb0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
27cc0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lumn..**.** ^The
27cd0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
27ce0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
27cf0 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  ces is a [prepar
27d00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
27d10 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
27d20 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
27d30 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
27d40 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
27d50 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
27d60 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
27d70 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
27d80 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
27d90 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
27da0 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
27db0 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f  n is column 0 fo
27dc0 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
27dd0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
27de0 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
27df0 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
27e00 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
27e10 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
27e20 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
27e30 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
27e40 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
27e50 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
27e60 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68  rn.** NULL.  ^Th
27e70 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68  ese routine migh
27e80 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55  t also return NU
27e90 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  LL if a memory a
27ea0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a  llocation error.
27eb0 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68  ** occurs.  ^Oth
27ec0 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
27ed0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
27ee0 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
27ef0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a  abase, table,.**
27f00 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20   or column that 
27f10 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
27f20 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
27f30 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41  d from..**.** ^A
27f40 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
27f50 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
27f60 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20  ose whose names 
27f70 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65  end with "16" re
27f80 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
27f90 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61  ncoded strings a
27fa0 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  nd the other fun
27fb0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
27fc0 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  F-8..**.** ^Thes
27fd0 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
27fe0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
27ff0 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
28000 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
28010 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
28020 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
28030 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
28040 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49   symbol..**.** I
28050 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
28060 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
28070 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
28080 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
28090 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
280a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
280b0 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
280c0 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
280d0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
280e0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
280f0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
28100 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
28110 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
28120 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
28130 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
28140 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
28150 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
28160 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
28170 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28180 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
28190 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
281a0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
281b0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
281c0 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  fined..*/.const 
281d0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
281e0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
281f0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
28200 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
28210 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
28220 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
28230 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
28240 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
28250 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
28260 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
28270 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
28280 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
28290 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
282a0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
282b0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
282c0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
282d0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
282e0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
282f0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
28300 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
28310 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
28320 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
28330 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
28340 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
28350 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
28360 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
28370 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
28380 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
28390 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
283a0 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
283b0 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
283c0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
283d0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
283e0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
283f0 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
28400 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
28410 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
28420 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
28430 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
28440 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
28450 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
28460 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
28470 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
28480 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
28490 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
284a0 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
284b0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
284c0 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
284d0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
284e0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
284f0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
28500 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
28510 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
28520 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
28530 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
28540 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
28550 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
28560 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
28570 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
28580 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
28590 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
285a0 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
285b0 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
285c0 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
285d0 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
285e0 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
285f0 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
28600 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
28610 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
28620 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
28630 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
28640 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
28650 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
28660 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
28670 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
28680 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
28690 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
286a0 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
286b0 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
286c0 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
286d0 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
286e0 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
286f0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
28700 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
28710 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
28720 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
28730 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
28740 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
28750 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
28760 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
28770 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
28780 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
28790 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
287a0 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
287b0 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
287c0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
287d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
287e0 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
287f0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
28800 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
28810 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
28820 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
28830 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
28840 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
28850 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
28860 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
28870 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28880 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
28890 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
288a0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
288b0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
288c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
288d0 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
288e0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
288f0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
28900 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
28910 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
28920 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
28930 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
28940 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
28950 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
28960 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
28970 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
28980 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
28990 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
289a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
289b0 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
289c0 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
289d0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
289e0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
289f0 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
28a00 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
28a10 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
28a20 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
28a30 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
28a40 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
28a50 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
28a60 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28a70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
28a80 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
28a90 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
28aa0 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
28ab0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
28ac0 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
28ad0 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
28ae0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
28af0 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
28b00 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
28b10 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
28b20 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
28b30 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
28b40 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
28b50 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
28b60 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
28b70 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
28b80 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
28b90 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
28ba0 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
28bb0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
28bc0 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
28bd0 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
28be0 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
28bf0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
28c00 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
28c10 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
28c20 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
28c30 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
28c40 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
28c50 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
28c60 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
28c70 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
28c80 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
28c90 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
28ca0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
28cb0 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
28cc0 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
28cd0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
28ce0 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
28cf0 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
28d00 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
28d10 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
28d20 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
28d30 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
28d40 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74  n an.** explicit
28d50 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
28d60 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
28d70 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
28d80 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
28d90 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
28da0 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
28db0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
28dc0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
28dd0 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
28de0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
28df0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
28e00 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
28e10 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
28e20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
28e30 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
28e40 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
28e50 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
28e60 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
28e70 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
28e80 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
28e90 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
28ea0 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
28eb0 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
28ec0 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
28ed0 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
28ee0 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
28ef0 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
28f00 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
28f10 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
28f20 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
28f30 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
28f40 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
28f50 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
28f60 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
28f70 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
28f80 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
28f90 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
28fa0 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
28fb0 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
28fc0 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
28fd0 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
28fe0 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
28ff0 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
29000 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
29010 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
29020 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
29030 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
29040 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
29050 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
29060 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
29070 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
29080 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
29090 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
290a0 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
290b0 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
290c0 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
290d0 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
290e0 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
290f0 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
29100 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
29110 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
29120 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
29130 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
29140 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
29150 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
29160 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
29170 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
29180 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
29190 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
291a0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
291b0 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
291c0 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
291d0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
291e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
291f0 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
29200 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
29210 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
29220 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
29230 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
29240 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
29250 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
29260 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
29270 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
29280 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
29290 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
292a0 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
292b0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
292c0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
292d0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
292e0 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
292f0 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
29300 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
29310 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
29320 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
29330 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
29340 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
29350 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
29360 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
29370 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
29380 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
29390 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
293a0 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  1, a call to.** 
293b0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
293c0 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61  ] was required a
293d0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65  fter sqlite3_ste
293e0 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79  p() returned any
293f0 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74  thing.** other t
29400 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
29410 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73   before any subs
29420 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
29430 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n of.** sqlite3_
29440 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65  step().  Failure
29450 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72   to reset the pr
29460 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29470 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
29480 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75  te3_reset()] wou
29490 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ld result in an 
294a0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
294b0 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73  return from.** s
294c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
294d0 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f  But after versio
294e0 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69  n 3.6.23.1, sqli
294f0 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e  te3_step() began
29500 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** calling [sql
29510 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75  ite3_reset()] au
29520 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
29530 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65  his circumstance
29540 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20   rather.** than 
29550 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
29560 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73  E_MISUSE].  This
29570 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72   is not consider
29580 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69  ed a compatibili
29590 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61  ty.** break beca
295a0 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74  use any applicat
295b0 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65  ion that ever re
295c0 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45  ceives an SQLITE
295d0 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a  _MISUSE error.**
295e0 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65   is broken by de
295f0 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b  finition.  The [
29600 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
29610 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  RESET] compile-t
29620 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61  ime option.** ca
29630 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73  n be used to res
29640 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20  tore the legacy 
29650 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
29660 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
29670 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
29680 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
29690 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
296a0 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
296b0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
296c0 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
296d0 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
296e0 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
296f0 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
29700 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
29710 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
29720 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
29730 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
29740 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
29750 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
29760 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
29770 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
29780 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
29790 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
297a0 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
297b0 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
297c0 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
297d0 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
297e0 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
297f0 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
29800 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
29810 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
29820 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
29830 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
29840 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
29850 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
29860 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
29870 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
29880 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
29890 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
298a0 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
298b0 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
298c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
298d0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
298e0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
298f0 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
29900 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
29910 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
29920 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
29930 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
29940 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
29950 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
29960 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
29970 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
29980 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
29990 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
299a0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
299b0 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20  esult set.**.** 
299c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
299d0 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
299e0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
299f0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
29a00 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
29a10 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
29a20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
29a30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29a40 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
29a50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
29a60 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
29a70 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
29a80 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
29a90 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
29aa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
29ab0 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
29ac0 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
29ad0 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
29ae0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
29af0 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
29b00 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
29b10 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
29b20 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
29b30 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
29b40 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e  LL pointer..** ^
29b50 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
29b60 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
29b70 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74  e returns 0 if t
29b80 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
29b90 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
29ba0 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
29bb0 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  d [SQLITE_DONE].
29bc0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64    ^The sqlite3_d
29bd0 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20  ata_count(P).** 
29be0 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d  will return non-
29bf0 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73  zero if previous
29c00 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
29c10 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
29c20 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52  ned.** [SQLITE_R
29c30 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74  OW], except in t
29c40 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b  he case of the [
29c50 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74  PRAGMA increment
29c60 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68  al_vacuum].** wh
29c70 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65  ere it always re
29c80 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65  turns zero since
29c90 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68   each step of th
29ca0 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a  at multi-step.**
29cb0 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20   pragma returns 
29cc0 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74  0 columns of dat
29cd0 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  a..**.** See als
29ce0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  o: [sqlite3_colu
29cf0 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  mn_count()].*/.i
29d00 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  nt sqlite3_data_
29d10 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
29d20 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
29d30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
29d40 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
29d50 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
29d60 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
29d70 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
29d80 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
29d90 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
29da0 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
29db0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
29dc0 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
29dd0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
29de0 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
29df0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
29e00 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
29e10 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
29e20 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
29e30 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
29e40 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
29e50 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
29e60 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
29e70 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
29e80 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
29e90 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
29ea0 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
29eb0 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
29ec0 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
29ed0 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
29ee0 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
29ef0 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
29f00 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
29f10 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
29f20 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
29f30 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
29f40 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
29f50 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
29f60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
29f70 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
29f80 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
29f90 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
29fa0 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
29fb0 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
29fc0 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
29fd0 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
29fe0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
29ff0 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
2a000 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
2a010 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
2a020 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
2a030 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a040 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
2a050 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
2a060 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
2a070 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2a080 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s}.**.** These r
2a090 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65  outines form the
2a0a0 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e   "result set" in
2a0b0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  terface..**.** ^
2a0c0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2a0d0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
2a0e0 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
2a0f0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
2a100 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
2a110 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
2a120 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
2a130 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
2a140 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
2a150 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
2a160 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a170 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
2a180 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
2a190 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
2a1a0 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
2a1b0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2a1c0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2a1d0 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
2a1e0 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
2a1f0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2a200 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
2a210 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
2a220 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
2a230 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
2a240 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
2a250 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
2a260 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2a270 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
2a280 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
2a290 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2a2a0 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
2a2b0 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
2a2c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2a2d0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
2a2e0 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
2a2f0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
2a300 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
2a310 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
2a320 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
2a330 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
2a340 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
2a350 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
2a360 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
2a370 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
2a380 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
2a390 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2a3a0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2a3b0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
2a3c0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2a3d0 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
2a3e0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
2a3f0 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
2a400 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2a410 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
2a420 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
2a430 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
2a440 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
2a450 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
2a460 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2a470 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
2a480 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
2a490 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
2a4a0 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
2a4b0 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
2a4c0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2a4d0 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
2a4e0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2a4f0 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
2a500 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
2a510 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
2a520 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2a530 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
2a540 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
2a550 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
2a560 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
2a570 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
2a580 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
2a590 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2a5a0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2a5b0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2a5c0 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
2a5d0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
2a5e0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
2a5f0 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
2a600 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
2a610 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
2a620 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
2a630 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
2a640 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
2a650 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
2a660 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
2a670 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
2a680 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
2a690 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
2a6a0 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
2a6b0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
2a6c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a6d0 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
2a6e0 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
2a6f0 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
2a700 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
2a710 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
2a720 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
2a730 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
2a740 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
2a750 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2a760 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
2a770 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
2a780 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
2a790 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
2a7a0 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
2a7b0 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
2a7c0 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
2a7d0 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
2a7e0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
2a7f0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2a800 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
2a810 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
2a820 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
2a830 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
2a840 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2a850 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2a860 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
2a870 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
2a880 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2a890 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
2a8a0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2a8b0 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
2a8c0 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
2a8d0 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
2a8e0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
2a8f0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2a900 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2a910 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
2a920 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
2a930 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2a940 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
2a950 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2a960 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
2a970 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
2a980 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2a990 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
2a9a0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2a9b0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
2a9c0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2a9d0 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
2a9e0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2a9f0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
2aa00 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
2aa10 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
2aa20 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  r UTF-16 string 
2aa30 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2aa40 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2aa50 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
2aa60 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2aa70 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2aa80 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
2aa90 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2aaa0 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  lt is a UTF-8 st
2aab0 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
2aac0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2aad0 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  6() converts.** 
2aae0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
2aaf0 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65  F-16 and then re
2ab00 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2ab10 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
2ab20 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2ab30 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
2ab40 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2ab50 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73  umn_bytes16() us
2ab60 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
2ab70 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
2ab80 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
2ab90 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72   to a UTF-16 str
2aba0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
2abb0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2abc0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
2abd0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2abe0 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
2abf0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2ac00 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2ac10 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
2ac20 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20  .** ^The values 
2ac30 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2ac40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2ac50 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  s()] and .** [sq
2ac60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ac70 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69  es16()] do not i
2ac80 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
2ac90 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74  terminators at t
2aca0 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
2acb0 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63   string.  ^For c
2acc0 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
2acd0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
2ace0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2acf0 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b  n_bytes()] and [
2ad00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2ad10 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68  ytes16()] are th
2ad20 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
2ad30 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
2ad40 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
2ad50 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
2ad60 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73  ..**.** ^Strings
2ad70 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2ad80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2ad90 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
2ada0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
2adb0 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
2adc0 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
2add0 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
2ade0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a  d.  ^The return.
2adf0 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
2ae00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2ae10 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
2ae20 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20  ength BLOB is a 
2ae30 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2ae40 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20  .** ^The object 
2ae50 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2ae60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2ae70 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
2ae80 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2ae90 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2aea0 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
2aeb0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2aec0 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
2aed0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
2aee0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
2aef0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
2af00 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2af10 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
2af20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2af30 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2af40 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
2af50 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2af60 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
2af70 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
2af80 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
2af90 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
2afa0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
2afb0 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
2afc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2afd0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
2afe0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2aff0 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62  s()], then the b
2b000 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2b010 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
2b020 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
2b030 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
2b040 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
2b050 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72  propriate.  ^For
2b060 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
2b070 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
2b080 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
2b090 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
2b0a0 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
2b0b0 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
2b0c0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
2b0d0 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
2b0e0 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
2b0f0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
2b100 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
2b110 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
2b120 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
2b130 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
2b140 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
2b150 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
2b160 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
2b170 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
2b180 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
2b190 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
2b1a0 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
2b1b0 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
2b1c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2b1d0 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
2b1e0 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
2b1f0 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
2b200 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2b210 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
2b220 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
2b230 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2b240 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2b250 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2b260 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2b270 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2b280 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2b290 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2b2a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2b2b0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
2b2c0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2b2d0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
2b2e0 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
2b2f0 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
2b300 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
2b310 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
2b320 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
2b330 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
2b340 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2b350 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2b360 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54  <td> Same as INT
2b370 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  EGER->TEXT.** <t
2b380 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
2b390 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2b3a0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
2b3b0 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65   float to intege
2b3c0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  r.** <tr><td>  F
2b3d0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45  LOAT   <td>   TE
2b3e0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
2b3f0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
2b400 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  e float.** <tr><
2b410 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
2b420 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
2b430 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e   Same as FLOAT->
2b440 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
2b450 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
2b460 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73  NTEGER   <td> Us
2b470 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
2b480 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2b490 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2b4a0 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  > Use atof().** 
2b4b0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
2b4c0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2b4d0 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
2b4e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
2b4f0 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
2b500 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
2b510 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
2b520 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
2b530 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2b540 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2b550 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
2b560 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28  T then use atof(
2b570 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
2b580 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45  LOB    <td>   TE
2b590 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61  XT    <td> Add a
2b5a0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2b5b0 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f   if needed.** </
2b5c0 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
2b5d0 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
2b5e0 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20  The table above 
2b5f0 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20  makes reference 
2b600 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  to standard C li
2b610 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20  brary functions 
2b620 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74  atoi().** and at
2b630 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f  of().  SQLite do
2b640 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73  es not really us
2b650 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  e these function
2b660 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a  s.  It has its.*
2b670 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74  * own equivalent
2b680 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e   internal routin
2b690 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20  es.  The atoi() 
2b6a0 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73  and atof() names
2b6b0 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20   are.** used in 
2b6c0 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72  the table for br
2b6d0 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73  evity and becaus
2b6e0 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c  e they are famil
2b6f0 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43  iar to most.** C
2b700 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a   programmers..**
2b710 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
2b720 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
2b730 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
2b740 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
2b750 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
2b760 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2b770 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
2b780 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
2b790 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
2b7a0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2b7b0 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
2b7c0 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f  ated..** Type co
2b7d0 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
2b7e0 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
2b7f0 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
2b800 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
2b810 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
2b820 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
2b830 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2b840 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
2b850 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2b860 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
2b870 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b880 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
2b890 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
2b8a0 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
2b8b0 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
2b8c0 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
2b8d0 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
2b8e0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
2b8f0 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
2b900 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
2b910 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2b920 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2b930 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2b940 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
2b950 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
2b960 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
2b970 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
2b980 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
2b990 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2b9a0 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
2b9b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2b9c0 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
2b9d0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2b9e0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
2b9f0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
2ba00 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
2ba10 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
2ba20 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
2ba30 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f   </ul>.**.** ^Co
2ba40 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
2ba50 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
2ba60 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
2ba70 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
2ba80 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
2ba90 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
2baa0 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
2bab0 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
2bac0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
2bad0 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
2bae0 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
2baf0 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20  references will 
2bb00 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
2bb10 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
2bb20 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
2bb30 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
2bb40 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
2bb50 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
2bb60 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61  etimes they.** a
2bb70 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  re not possible 
2bb80 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
2bb90 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
2bba0 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
2bbb0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66  d..**.** The saf
2bbc0 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20  est and easiest 
2bbd0 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69  to remember poli
2bbe0 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
2bbf0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
2bc00 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
2bc10 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
2bc20 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  **.** <ul>.**  <
2bc30 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2bc40 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
2bc50 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2bc60 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
2bc70 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2bc80 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
2bc90 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2bca0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2bcb0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
2bcc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2bcd0 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
2bce0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2bcf0 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
2bd00 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2bd10 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
2bd20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
2bd30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2bd40 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  ext(),.** sqlite
2bd50 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
2bd60 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2bd70 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
2bd80 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
2bd90 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68  esult.** into th
2bda0 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74  e desired format
2bdb0 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
2bdc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2bdd0 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  es() or.** sqlit
2bde0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2bdf0 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20  6() to find the 
2be00 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
2be10 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
2be20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69  calls.** to sqli
2be30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2be40 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
2be50 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
2be60 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
2be70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2be80 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74  16(), and do not
2be90 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
2bea0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2beb0 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61  t16().** with ca
2bec0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2bed0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
2bee0 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65  *.** ^The pointe
2bef0 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
2bf00 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
2bf10 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
2bf20 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
2bf30 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
2bf40 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
2bf50 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
2bf60 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
2bf70 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2bf80 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
2bf90 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70    ^The memory sp
2bfa0 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
2bfb0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
2bfc0 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61  BLOBs is freed a
2bfd0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
2bfe0 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73  o <b>not</b> pas
2bff0 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
2c000 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69  eturned.** [sqli
2c010 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2c020 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  )], [sqlite3_col
2c030 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63  umn_text()], etc
2c040 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  . into.** [sqlit
2c050 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
2c060 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20  * ^(If a memory 
2c070 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
2c080 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
2c090 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
2c0a0 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
2c0b0 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
2c0c0 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
2c0d0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
2c0e0 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
2c0f0 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
2c100 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
2c110 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
2c120 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
2c130 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
2c140 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
2c150 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
2c160 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
2c170 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
2c180 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  M].)^.*/.const v
2c190 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2c1a0 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
2c1b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2c1c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2c1d0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
2c1e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2c1f0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
2c200 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2c210 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2c220 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c  int iCol);.doubl
2c230 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2c240 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
2c250 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2c260 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2c270 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
2c280 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2c290 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
2c2a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c2b0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
2c2c0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2c2d0 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
2c2e0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2c2f0 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
2c300 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2c310 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2c320 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c330 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
2c340 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
2c350 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2c360 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
2c370 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2c380 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a  .sqlite3_value *
2c390 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2c3a0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
2c3b0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
2c3c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c3d0 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
2c3e0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
2c3f0 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ect.**.** ^The s
2c400 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2c410 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
2c420 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
2c430 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c440 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  ment]..** ^If th
2c450 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
2c460 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  aluation of the 
2c470 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e  statement encoun
2c480 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a  tered no errors.
2c490 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61  ** or if the sta
2c4a0 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20  tement is never 
2c4b0 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20  been evaluated, 
2c4c0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e  then sqlite3_fin
2c4d0 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a  alize() returns.
2c4e0 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e  ** SQLITE_OK.  ^
2c4f0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2c500 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
2c510 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69   statement S fai
2c520 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  led, then.** sql
2c530 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
2c540 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70   returns the app
2c550 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
2c560 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
2c570 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
2c580 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
2c590 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
2c5a0 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  ) routine can be
2c5b0 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
2c5c0 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74  oint during.** t
2c5d0 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66  he life cycle of
2c5e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c5f0 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f  ment] S:.** befo
2c600 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69  re statement S i
2c610 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64  s ever evaluated
2c620 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f  , after.** one o
2c630 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20  r more calls to 
2c640 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2c650 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20  ], or after any 
2c660 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  call.** to [sqli
2c670 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61  te3_step()] rega
2c680 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
2c690 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61  r or not the sta
2c6a0 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f  tement has.** co
2c6b0 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f  mpleted executio
2c6c0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69  n..**.** ^Invoki
2c6d0 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ng sqlite3_final
2c6e0 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20  ize() on a NULL 
2c6f0 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72  pointer is a har
2c700 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
2c710 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
2c720 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65  on must finalize
2c730 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64   every [prepared
2c740 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f   statement] in o
2c750 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  rder to avoid.**
2c760 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e   resource leaks.
2c770 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f    It is a grievo
2c780 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65  us error for the
2c790 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
2c7a0 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20  try to use.** a 
2c7b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c7c0 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
2c7d0 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20  been finalized. 
2c7e0 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72   Any use of a pr
2c7f0 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
2c800 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
2c810 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20   been finalized 
2c820 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  can result in un
2c830 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75  defined and.** u
2c840 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
2c850 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66  ior such as segf
2c860 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63  aults and heap c
2c870 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e  orruption..*/.in
2c880 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
2c890 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
2c8a0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2c8b0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
2c8c0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2c8d0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
2c8e0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
2c8f0 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
2c900 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
2c910 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
2c920 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
2c930 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
2c940 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
2c950 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
2c960 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
2c970 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
2c980 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
2c990 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
2c9a0 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
2c9b0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2c9c0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
2c9d0 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
2c9e0 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
2c9f0 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
2ca00 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
2ca10 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
2ca20 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
2ca30 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
2ca40 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
2ca50 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
2ca60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ca70 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
2ca80 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
2ca90 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
2caa0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
2cab0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
2cac0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2cad0 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
2cae0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2caf0 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
2cb00 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
2cb10 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
2cb20 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
2cb30 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
2cb40 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
2cb50 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
2cb60 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
2cb70 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
2cb80 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
2cb90 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
2cba0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
2cbb0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
2cbc0 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
2cbd0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2cbe0 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
2cbf0 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
2cc00 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
2cc10 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
2cc20 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
2cc30 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
2cc40 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2cc50 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
2cc60 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
2cc70 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
2cc80 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2cc90 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
2cca0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2ccb0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
2ccc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
2ccd0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2cce0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2ccf0 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
2cd00 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
2cd10 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
2cd20 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
2cd30 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
2cd40 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
2cd50 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
2cd60 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2cd70 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
2cd80 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
2cd90 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2cda0 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ons}.**.** ^Thes
2cdb0 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  e functions (col
2cdc0 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
2cdd0 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
2cde0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
2cdf0 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
2ce00 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
2ce10 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
2ce20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
2ce30 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
2ce40 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
2ce50 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
2ce60 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
2ce70 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65  y differences be
2ce80 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72  tween.** these r
2ce90 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20  outines are the 
2cea0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78  text encoding ex
2ceb0 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68  pected for.** th
2cec0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2ced0 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20  er (the name of 
2cee0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  the function bei
2cef0 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61  ng created).** a
2cf00 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  nd the presence 
2cf10 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20  or absence of a 
2cf20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
2cf30 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ack for.** the a
2cf40 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
2cf50 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
2cf60 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2cf70 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
2cf80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2cf90 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
2cfa0 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
2cfb0 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e   to be added.  ^
2cfc0 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  If an applicatio
2cfd0 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  n uses more than
2cfe0 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
2cff0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e   connection then
2d000 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2d010 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2d020 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
2d030 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61  .** to each data
2d040 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2d050 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
2d060 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  * ^The second pa
2d070 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
2d080 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
2d090 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
2d0a0 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
2d0b0 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e  fined.  ^The len
2d0c0 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
2d0d0 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
2d0e0 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46  5 bytes in a UTF
2d0f0 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61  -8.** representa
2d100 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20  tion, exclusive 
2d110 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  of the zero-term
2d120 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74  inator.  ^Note t
2d130 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  hat the name.** 
2d140 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
2d150 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20  in UTF-8 bytes, 
2d160 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e  not characters n
2d170 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e  or UTF-16 bytes.
2d180 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d    .** ^Any attem
2d190 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
2d1a0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
2d1b0 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
2d1c0 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
2d1d0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69  LITE_MISUSE] bei
2d1e0 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
2d1f0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  ** ^The third pa
2d200 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a  rameter (nArg).*
2d210 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
2d220 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
2d230 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
2d240 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
2d250 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68  te takes. ^If th
2d260 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
2d270 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  -1, then the SQL
2d280 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
2d290 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
2d2a0 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
2d2b0 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65   arguments betwe
2d2c0 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d  en 0 and the lim
2d2d0 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71  it.** set by [sq
2d2e0 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
2d2f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
2d300 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74  ION_ARG]).  If t
2d310 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
2d320 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
2d330 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72  an -1 or greater
2d340 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74   than 127 then t
2d350 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  he behavior is.*
2d360 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
2d370 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
2d380 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
2d390 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
2d3a0 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
2d3b0 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
2d3c0 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
2d3d0 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
2d3e0 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
2d3f0 65 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20  ers.  Every SQL 
2d400 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2d410 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  ntation must be 
2d420 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  able to work.** 
2d430 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d  with UTF-8, UTF-
2d440 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62  16le, or UTF-16b
2d450 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70  e.  But some imp
2d460 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
2d470 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69   be.** more effi
2d480 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65  cient with one e
2d490 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f  ncoding than ano
2d4a0 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69  ther.  ^An appli
2d4b0 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e  cation may.** in
2d4c0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  voke sqlite3_cre
2d4d0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f  ate_function() o
2d4e0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
2d4f0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75  _function16() mu
2d500 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20  ltiple.** times 
2d510 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75  with the same fu
2d520 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20  nction but with 
2d530 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73  different values
2d540 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a   of eTextRep..**
2d550 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
2d560 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2d570 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
2d580 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
2d590 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
2d5a0 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
2d5b0 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
2d5c0 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
2d5d0 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
2d5e0 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69  n..** If there i
2d5f0 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  s only a single 
2d600 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2d610 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61  hich does not ca
2d620 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20  re what text.** 
2d630 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
2d640 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  , then the fourt
2d650 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  h argument shoul
2d660 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59  d be [SQLITE_ANY
2d670 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  ]..**.** ^(The f
2d680 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
2d690 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
2d6a0 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
2d6b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
2d6c0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
2d6d0 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
2d6e0 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
2d6f0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
2d700 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a  er_data()].)^.**
2d710 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20  .** ^The sixth, 
2d720 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68  seventh and eigh
2d730 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78  th parameters, x
2d740 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20  Func, xStep and 
2d750 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70  xFinal, are.** p
2d760 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e  ointers to C-lan
2d770 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20  guage functions 
2d780 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
2d790 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2d7a0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e  or.** aggregate.
2d7b0 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66   ^A scalar SQL f
2d7c0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
2d7d0 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
2d7e0 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a  on of the xFunc.
2d7f0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  ** callback only
2d800 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  ; NULL pointers 
2d810 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61  must be passed a
2d820 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20  s the xStep and 
2d830 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65  xFinal.** parame
2d840 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67  ters. ^An aggreg
2d850 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
2d860 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
2d870 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78  lementation of x
2d880 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
2d890 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e  al and NULL poin
2d8a0 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73  ter must be pass
2d8b0 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54  ed for xFunc. ^T
2d8c0 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73  o delete an exis
2d8d0 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63  ting.** SQL func
2d8e0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
2d8f0 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69  e, pass NULL poi
2d900 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68  nters for all th
2d910 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ree function.** 
2d920 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a  callbacks..**.**
2d930 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20   ^(If the ninth 
2d940 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2d950 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2d960 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  tion_v2() is not
2d970 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69   NULL,.** then i
2d980 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20  t is destructor 
2d990 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
2d9a0 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
2d9b0 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75  . .** The destru
2d9c0 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20  ctor is invoked 
2d9d0 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  when the functio
2d9e0 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69  n is deleted, ei
2d9f0 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a  ther by being.**
2da00 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77   overloaded or w
2da10 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
2da20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
2da30 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65  es.)^.** ^The de
2da40 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f  structor is also
2da50 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20   invoked if the 
2da60 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
2da70 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2da80 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a  on_v2() fails..*
2da90 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74  * ^When the dest
2daa0 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
2dab0 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72  of the tenth par
2dac0 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65  ameter is invoke
2dad0 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73  d, it.** is pass
2dae0 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  ed a single argu
2daf0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
2db00 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c  copy of the appl
2db10 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a  ication data .**
2db20 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77   pointer which w
2db30 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72  as the fifth par
2db40 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2db50 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2db60 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49  n_v2()..**.** ^I
2db70 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  t is permitted t
2db80 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69  o register multi
2db90 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
2dba0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ons of the same.
2dbb0 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74  ** functions wit
2dbc0 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
2dbd0 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20  but with either 
2dbe0 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72  differing number
2dbf0 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  s of.** argument
2dc00 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70  s or differing p
2dc10 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
2dc20 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74  codings.  ^SQLit
2dc30 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68  e will use.** th
2dc40 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2dc50 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65   that most close
2dc60 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
2dc70 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
2dc80 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
2dc90 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e  is used.  ^A fun
2dca0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2dcb0 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d  tion with a non-
2dcc0 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67  negative.** nArg
2dcd0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
2dce0 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61  better match tha
2dcf0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  n a function imp
2dd00 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
2dd10 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e  .** a negative n
2dd20 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  Arg.  ^A functio
2dd30 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66  n where the pref
2dd40 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
2dd50 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74  ing.** matches t
2dd60 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f  he database enco
2dd70 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72  ding is a better
2dd80 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61  .** match than a
2dd90 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
2dda0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
2ddb0 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20  different.  .** 
2ddc0 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
2ddd0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
2dde0 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74  ifference is bet
2ddf0 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64  ween UTF16le and
2de00 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61   UTF16be.** is a
2de10 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68   closer match th
2de20 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
2de30 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
2de40 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a   difference is.*
2de50 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61  * between UTF8 a
2de60 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20  nd UTF16..**.** 
2de70 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69  ^Built-in functi
2de80 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c  ons may be overl
2de90 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70  oaded by new app
2dea0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2deb0 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
2dec0 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  * ^An applicatio
2ded0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2dee0 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  on is permitted 
2def0 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a  to call other.**
2df00 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
2df10 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75  es.  However, su
2df20 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f  ch calls must no
2df30 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64  t.** close the d
2df40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2df50 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20  on nor finalize 
2df60 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65  or reset the pre
2df70 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2df80 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  nt in which the 
2df90 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
2dfa0 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ing..*/.int sqli
2dfb0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2dfc0 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
2dfd0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
2dfe0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
2dff0 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
2e000 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
2e010 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
2e020 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
2e030 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2e040 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2e050 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
2e060 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2e070 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2e080 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2e090 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
2e0a0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
2e0b0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2e0c0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
2e0d0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
2e0e0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
2e0f0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
2e100 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
2e110 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
2e120 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
2e130 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
2e140 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2e150 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2e160 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
2e170 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2e180 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2e190 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
2e1a0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
2e1b0 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  xt*).);.int sqli
2e1c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2e1d0 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
2e1e0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
2e1f0 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
2e200 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
2e210 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
2e220 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
2e230 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
2e240 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2e250 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2e260 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
2e270 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
2e280 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2e290 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2e2a0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
2e2b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a  ite3_context*),.
2e2c0 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
2e2d0 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  )(void*).);../*.
2e2e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78  ** CAPI3REF: Tex
2e2f0 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a  t Encodings.**.*
2e300 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
2e310 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20   define integer 
2e320 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65  codes that repre
2e330 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73  sent the various
2e340 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  .** text encodin
2e350 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  gs supported by 
2e360 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
2e370 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20  ne SQLITE_UTF8  
2e380 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
2e390 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
2e3a0 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69  E        2.#defi
2e3b0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42  ne SQLITE_UTF16B
2e3c0 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  E        3.#defi
2e3d0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20  ne SQLITE_UTF16 
2e3e0 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a           4    /*
2e3f0 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65   Use native byte
2e400 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e   order */.#defin
2e410 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20  e SQLITE_ANY    
2e420 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20          5    /* 
2e430 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2e440 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  unction only */.
2e450 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2e460 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20  TF16_ALIGNED  8 
2e470 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
2e480 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f  eate_collation o
2e490 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  nly */../*.** CA
2e4a0 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74  PI3REF: Deprecat
2e4b0 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  ed Functions.** 
2e4c0 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a  DEPRECATED.**.**
2e4d0 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
2e4e0 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64   are [deprecated
2e4f0 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  ].  In order to 
2e500 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b  maintain.** back
2e510 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
2e520 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63  ity with older c
2e530 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74  ode, these funct
2e540 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a  ions continue .*
2e550 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  * to be supporte
2e560 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77  d.  However, new
2e570 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   applications sh
2e580 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68  ould avoid.** th
2e590 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66  e use of these f
2e5a0 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65  unctions.  To he
2e5b0 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f  lp encourage peo
2e5c0 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  ple to avoid.** 
2e5d0 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63  using these func
2e5e0 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f  tions, we are no
2e5f0 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20  t going to tell 
2e600 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f  you what they do
2e610 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
2e620 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41  ITE_OMIT_DEPRECA
2e630 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  TED.SQLITE_DEPRE
2e640 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
2e650 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e  3_aggregate_coun
2e660 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
2e670 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
2e680 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2e690 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74  e3_expired(sqlit
2e6a0 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
2e6b0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
2e6c0 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
2e6d0 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
2e6e0 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
2e6f0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
2e700 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
2e710 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72  sqlite3_global_r
2e720 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51  ecover(void);.SQ
2e730 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2e740 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72  void sqlite3_thr
2e750 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64  ead_cleanup(void
2e760 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
2e770 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
2e780 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f  _memory_alarm(vo
2e790 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
2e7a0 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76  te3_int64,int),v
2e7b0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
2e7c0 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  64);.#endif../*.
2e7d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
2e7e0 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74  aining SQL Funct
2e7f0 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61  ion Parameter Va
2e800 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  lues.**.** The C
2e810 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d  -language implem
2e820 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20  entation of SQL 
2e830 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
2e840 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a  gregates uses.**
2e850 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74   this set of int
2e860 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20  erface routines 
2e870 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61  to access the pa
2e880 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f  rameter values o
2e890 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f  n.** the functio
2e8a0 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a  n or aggregate..
2e8b0 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20  **.** The xFunc 
2e8c0 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63  (for scalar func
2e8d0 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20  tions) or xStep 
2e8e0 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29  (for aggregates)
2e8f0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
2e900 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
2e910 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
2e920 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
2e930 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
2e940 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61  ** define callba
2e950 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  cks that impleme
2e960 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
2e970 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
2e980 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20  tes..** The 3rd 
2e990 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2e9a0 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20  se callbacks is 
2e9b0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
2e9c0 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74  ters to.** [prot
2e9d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e9e0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54  lue] objects.  T
2e9f0 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c  here is one [sql
2ea00 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2ea10 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70  ct for.** each p
2ea20 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2ea30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54  SQL function.  T
2ea40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
2ea50 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74  e used to.** ext
2ea60 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d  ract values from
2ea70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
2ea80 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
2ea90 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2eaa0 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74  es work only wit
2eab0 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  h [protected sql
2eac0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2ead0 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  cts..** Any atte
2eae0 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65  mpt to use these
2eaf0 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20   routines on an 
2eb00 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2eb10 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
2eb20 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e  bject results in
2eb30 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
2eb40 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ior..**.** ^Thes
2eb50 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
2eb60 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f  just like the co
2eb70 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c  rresponding [col
2eb80 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
2eb90 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20  ions].** except 
2eba0 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74  that  these rout
2ebb0 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67  ines take a sing
2ebc0 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  le [protected sq
2ebd0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2ebe0 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ect.** pointer i
2ebf0 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c  nstead of a [sql
2ec00 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e  ite3_stmt*] poin
2ec10 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67  ter and an integ
2ec20 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  er column number
2ec30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2ec40 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2ec50 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78  6() interface ex
2ec60 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20  tracts a UTF-16 
2ec70 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65  string.** in the
2ec80 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64   native byte-ord
2ec90 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d  er of the host m
2eca0 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a  achine.  ^The.**
2ecb0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2ecc0 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71  ext16be() and sq
2ecd0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2ece0 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  16le() interface
2ecf0 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46  s.** extract UTF
2ed00 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62  -16 strings as b
2ed10 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69  ig-endian and li
2ed20 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70  ttle-endian resp
2ed30 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
2ed40 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  ^(The sqlite3_va
2ed50 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
2ed60 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
2ed70 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a  empts to apply.*
2ed80 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69  * numeric affini
2ed90 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e  ty to the value.
2eda0 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
2edb0 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a  t an attempt is.
2edc0 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65  ** made to conve
2edd0 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  rt the value to 
2ede0 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c  an integer or fl
2edf0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49  oating point.  I
2ee00 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76  f.** such a conv
2ee10 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62  ersion is possib
2ee20 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  le without loss 
2ee30 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28  of information (
2ee40 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64  in other.** word
2ee50 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  s, if the value 
2ee60 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74  is a string that
2ee70 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75   looks like a nu
2ee80 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68  mber).** then th
2ee90 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  e conversion is 
2eea0 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65  performed.  Othe
2eeb0 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73  rwise no convers
2eec0 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54  ion occurs..** T
2eed0 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  he [SQLITE_INTEG
2eee0 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61  ER | datatype] a
2eef0 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20  fter conversion 
2ef00 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a  is returned.)^.*
2ef10 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20  *.** Please pay 
2ef20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e  particular atten
2ef30 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74  tion to the fact
2ef40 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65   that the pointe
2ef50 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  r returned.** fr
2ef60 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  om [sqlite3_valu
2ef70 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  e_blob()], [sqli
2ef80 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
2ef90 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
2efa0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
2efb0 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64  ] can be invalid
2efc0 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71  ated by a subseq
2efd0 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  uent call to.** 
2efe0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2eff0 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ytes()], [sqlite
2f000 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
2f010 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
2f020 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
2f030 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
2f040 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _text16()]..**.*
2f050 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2f060 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
2f070 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
2f080 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53  read as.** the S
2f090 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  QL function that
2f0a0 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73   supplied the [s
2f0b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70  qlite3_value*] p
2f0c0 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f  arameters..*/.co
2f0d0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2f0e0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c  3_value_blob(sql
2f0f0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2f100 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2f110 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61  bytes(sqlite3_va
2f120 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
2f130 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
2f140 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2f150 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
2f160 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71  _value_double(sq
2f170 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2f180 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2f190 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  _int(sqlite3_val
2f1a0 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ue*);.sqlite3_in
2f1b0 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64 sqlite3_valu
2f1c0 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  e_int64(sqlite3_
2f1d0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75  value*);.const u
2f1e0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
2f1f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2f200 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2f210 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2f220 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2f230 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
2f240 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
2f250 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2f260 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76  xt16le(sqlite3_v
2f270 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
2f280 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
2f290 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  e_text16be(sqlit
2f2a0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
2f2b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
2f2c0 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
2f2d0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
2f2e0 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
2f2f0 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
2f300 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2f310 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72  REF: Obtain Aggr
2f320 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43  egate Function C
2f330 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70  ontext.**.** Imp
2f340 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
2f350 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
2f360 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73  nctions use this
2f370 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  .** routine to a
2f380 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66  llocate memory f
2f390 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72  or storing their
2f3a0 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54   state..**.** ^T
2f3b0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
2f3c0 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
2f3d0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
2f3e0 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
2f3f0 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72  ed .** for a par
2f400 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74  ticular aggregat
2f410 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69  e function, SQLi
2f420 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20  te.** allocates 
2f430 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72  N of memory, zer
2f440 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d  oes out that mem
2f450 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73  ory, and returns
2f460 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
2f470 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e   the new memory.
2f480 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20   ^On second and 
2f490 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
2f4a0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61   to.** sqlite3_a
2f4b0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2f4c0 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  () for the same 
2f4d0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
2f4e0 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20  on instance,.** 
2f4f0 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20  the same buffer 
2f500 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71  is returned.  Sq
2f510 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2f520 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72  context() is nor
2f530 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  mally.** called 
2f540 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e  once for each in
2f550 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
2f560 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61  xStep callback a
2f570 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c  nd then one.** l
2f580 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68  ast time when th
2f590 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  e xFinal callbac
2f5a0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  k is invoked.  ^
2f5b0 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61  (When no rows ma
2f5c0 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67  tch.** an aggreg
2f5d0 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78  ate query, the x
2f5e0 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20  Step() callback 
2f5f0 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65  of the aggregate
2f600 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70   function.** imp
2f610 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e  lementation is n
2f620 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20  ever called and 
2f630 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c  xFinal() is call
2f640 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e  ed exactly once.
2f650 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73  .** In those cas
2f660 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72  es, sqlite3_aggr
2f670 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
2f680 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20  might be called 
2f690 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74  for the.** first
2f6a0 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69   time from withi
2f6b0 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a  n xFinal().)^.**
2f6c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2f6d0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2f6e0 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
2f6f0 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
2f700 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a  ointer if N is.*
2f710 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  * less than or e
2f720 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20  qual to zero or 
2f730 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
2f740 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72  cate error occur
2f750 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61  s..**.** ^(The a
2f760 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61  mount of space a
2f770 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
2f780 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2f790 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a  ntext(C,N) is.**
2f7a0 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
2f7b0 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f  he N parameter o
2f7c0 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66  n first successf
2f7d0 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69  ul call.  Changi
2f7e0 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  ng the.** value 
2f7f0 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65  of N in subseque
2f800 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
2f810 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2f820 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a  text() within.**
2f830 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
2f840 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
2f850 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72  tance will not r
2f860 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  esize the memory
2f870 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29  .** allocation.)
2f880 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
2f890 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
2f8a0 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ees the memory a
2f8b0 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20  llocated by .** 
2f8c0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2f8d0 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e  e_context() when
2f8e0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71   the aggregate q
2f8f0 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
2f900 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
2f910 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
2f920 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  e a copy of the.
2f930 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
2f940 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
2f950 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
2f960 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
2f970 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
2f980 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61  e xStep or xFina
2f990 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  l callback routi
2f9a0 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
2f9b0 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
2f9c0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  .** function..**
2f9d0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
2f9e0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
2f9f0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
2fa00 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
2fa10 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
2fa20 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
2fa30 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
2fa40 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  *sqlite3_aggrega
2fa50 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
2fa60 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2fa70 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
2fa80 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
2fa90 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
2faa0 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
2fab0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2fac0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2fad0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
2fae0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
2faf0 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44  t was the pUserD
2fb00 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74  ata parameter (t
2fb10 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
2fb20 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
2fb30 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2fb40 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
2fb50 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2fb60 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
2fb70 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
2fb80 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
2fb90 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
2fba0 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
2fbb0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
2fbc0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
2fbd0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
2fbe0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
2fbf0 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70  which.** the app
2fc00 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2fc10 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
2fc20 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
2fc30 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
2fc40 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2fc50 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2fc60 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
2fc70 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e  nnection For Fun
2fc80 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
2fc90 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e sqlite3_contex
2fca0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e  t_db_handle() in
2fcb0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2fcc0 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
2fcd0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2fce0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2fcf0 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70  tion] (the 1st p
2fd00 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
2fd10 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
2fd20 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
2fd30 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
2fd40 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2fd50 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
2fd60 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
2fd70 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
2fd80 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
2fd90 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f  ned function..*/
2fda0 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65  .sqlite3 *sqlite
2fdb0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
2fdc0 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  dle(sqlite3_cont
2fdd0 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
2fde0 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e  PI3REF: Function
2fdf0 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a   Auxiliary Data.
2fe00 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77  **.** The follow
2fe10 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ing two function
2fe20 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
2fe30 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
2fe40 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f  tions to.** asso
2fe50 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77  ciate metadata w
2fe60 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
2fe70 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
2fe80 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
2fe90 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
2fea0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
2feb0 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
2fec0 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
2fed0 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
2fee0 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
2fef0 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
2ff00 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61  ociated metadata
2ff10 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65   may be preserve
2ff20 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62  d. This may.** b
2ff30 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d  e used, for exam
2ff40 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65  ple, to add a re
2ff50 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e  gular-expression
2ff60 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72   matching scalar
2ff70 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  .** function. Th
2ff80 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69  e compiled versi
2ff90 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61  on of the regula
2ffa0 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20  r expression is 
2ffb0 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74  stored as.** met
2ffc0 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
2ffd0 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61   with the SQL va
2ffe0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
2fff0 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
30000 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e  sion.** pattern.
30010 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72    The compiled r
30020 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
30030 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20  n can be reused 
30040 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69  on multiple.** i
30050 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
30060 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
30070 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67  so that the orig
30080 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72  inal pattern str
30090 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ing.** does not 
300a0 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d  need to be recom
300b0 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e  piled on each in
300c0 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  vocation..**.** 
300d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
300e0 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
300f0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
30100 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
30110 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  tadata.** associ
30120 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  ated by the sqli
30130 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
30140 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  ) function with 
30150 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
30160 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65  .** value to the
30170 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
30180 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e  ined function. ^
30190 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68  If no metadata h
301a0 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20  as been ever.** 
301b0 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65  been set for the
301c0 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66   Nth argument of
301d0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f   the function, o
301e0 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70  r if the corresp
301f0 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  onding.** functi
30200 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  on parameter has
30210 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74   changed since t
30220 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73  he meta-data was
30230 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71   set,.** then sq
30240 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
30250 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  a() returns a NU
30260 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
30270 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
30280 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
30290 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65  erface saves the
302a0 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69   metadata.** poi
302b0 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33  nted to by its 3
302c0 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  rd parameter as 
302d0 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72  the metadata for
302e0 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67   the N-th.** arg
302f0 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70  ument of the app
30300 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
30310 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73   function.  Subs
30320 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
30330 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  to sqlite3_get_a
30340 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72  uxdata() might r
30350 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c  eturn this data,
30360 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f   if it has.** no
30370 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64  t been destroyed
30380 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e  ..** ^If it is n
30390 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20  ot NULL, SQLite 
303a0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
303b0 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75  destructor.** fu
303c0 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20  nction given by 
303d0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
303e0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  r to sqlite3_set
303f0 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a  _auxdata() on.**
30400 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68   the metadata wh
30410 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
30420 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ding function pa
30430 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a  rameter changes.
30440 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53  ** or when the S
30450 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
30460 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65  pletes, whicheve
30470 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a  r comes first..*
30480 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66  *.** SQLite is f
30490 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20  ree to call the 
304a0 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64  destructor and d
304b0 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20  rop metadata on 
304c0 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  any.** parameter
304d0 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e   of any function
304e0 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e   at any time.  ^
304f0 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74  The only guarant
30500 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68  ee is that.** th
30510 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c  e destructor wil
30520 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f  l be called befo
30530 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  re the metadata 
30540 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a  is dropped..**.*
30550 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c  * ^(In practice,
30560 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65   metadata is pre
30570 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66  served between f
30580 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f  unction calls fo
30590 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73  r.** expressions
305a0 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61   that are consta
305b0 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  nt at compile ti
305c0 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65  me. This include
305d0 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c  s literal.** val
305e0 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74  ues and [paramet
305f0 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  ers].)^.**.** Th
30600 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
30610 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
30620 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
30630 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
30640 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
30650 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
30660 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  d *sqlite3_get_a
30670 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
30680 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b  ontext*, int N);
30690 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65  .void sqlite3_se
306a0 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
306b0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
306c0 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28  N, void*, void (
306d0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a  *)(void*));.../*
306e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
306f0 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67  nstants Defining
30700 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63   Special Destruc
30710 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a  tor Behavior.**.
30720 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
30730 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20  cial values for 
30740 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
30750 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
30760 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
30770 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
30780 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
30790 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
307a0 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73  )].  ^If the des
307b0 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
307c0 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
307d0 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
307e0 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
307f0 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
30800 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
30810 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
30820 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
30830 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
30840 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45    ^The.** SQLITE
30850 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
30860 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
30870 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
30880 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
30890 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
308a0 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
308b0 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
308c0 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
308d0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
308e0 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
308f0 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
30900 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73  typedef is neces
30910 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f  sary to work aro
30920 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20  und problems in 
30930 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63  certain.** C++ c
30940 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74  ompilers.  See t
30950 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a  icket #2191..*/.
30960 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
30970 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
30980 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a  r_type)(void*);.
30990 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
309a0 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c  TATIC      ((sql
309b0 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
309c0 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20  type)0).#define 
309d0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
309e0 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
309f0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29  tructor_type)-1)
30a00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30a10 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65  : Setting The Re
30a20 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46  sult Of An SQL F
30a30 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68  unction.**.** Th
30a40 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
30a50 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75   used by the xFu
30a60 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  nc or xFinal cal
30a70 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69  lbacks that.** i
30a80 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e  mplement SQL fun
30a90 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
30aa0 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b  gates.  See.** [
30ab0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
30ac0 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
30ad0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
30ae0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
30af0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
30b00 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
30b10 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
30b20 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68  s work very much
30b30 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d   like the [param
30b40 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61  eter binding] fa
30b50 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74  mily of.** funct
30b60 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e  ions used to bin
30b70 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
30b80 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70   parameters in p
30b90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30ba0 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  ts..** Refer to 
30bb0 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  the [SQL paramet
30bc0 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  er] documentatio
30bd0 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
30be0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
30bf0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30c00 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69  _result_blob() i
30c10 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
30c20 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
30c30 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
30c40 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
30c50 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20   to be the BLOB 
30c60 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73  whose content is
30c70 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62   pointed.** to b
30c80 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  y the second par
30c90 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68  ameter and which
30ca0 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67   is N bytes long
30cb0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a   where N is the.
30cc0 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
30cd0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
30ce0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
30cf0 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  roblob() interfa
30d00 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75  ces set the resu
30d10 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
30d20 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
30d30 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
30d40 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e  a BLOB containin
30d50 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79  g all zero.** by
30d60 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20  tes and N bytes 
30d70 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e  in size, where N
30d80 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
30d90 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
30da0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
30db0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
30dc0 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  uble() interface
30dd0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
30de0 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
30df0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
30e00 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
30e10 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
30e20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a  value specified.
30e30 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72  ** by its 2nd ar
30e40 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
30e50 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
30e60 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
30e70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
30e80 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73  or16() functions
30e90 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d  .** cause the im
30ea0 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75  plemented SQL fu
30eb0 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20  nction to throw 
30ec0 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a  an exception..**
30ed0 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
30ee0 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  e string pointed
30ef0 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e   to by the.** 2n
30f00 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
30f10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
30f20 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
30f30 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
30f40 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74  ).** as the text
30f50 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
30f60 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69  sage.  ^SQLite i
30f70 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72  nterprets the er
30f80 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73  ror.** message s
30f90 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
30fa0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
30fb0 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c  ) as UTF-8. ^SQL
30fc0 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ite.** interpret
30fd0 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f  s the string fro
30fe0 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
30ff0 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54  _error16() as UT
31000 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a  F-16 in native.*
31010 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e  * byte order.  ^
31020 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
31030 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
31040 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
31050 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
31060 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
31070 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  is negative then
31080 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73   SQLite takes as
31090 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
310a0 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75  ssage all text u
310b0 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  p through the fi
310c0 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
310d0 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
310e0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
310f0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
31100 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73  _error() or.** s
31110 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31120 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e  ror16() is non-n
31130 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
31140 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d  ite takes that m
31150 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f  any.** bytes (no
31160 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72  t characters) fr
31170 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
31180 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f  eter as the erro
31190 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54  r message..** ^T
311a0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
311b0 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
311c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
311d0 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  or16().** routin
311e0 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74  es make a privat
311f0 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72  e copy of the er
31200 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
31210 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20   before.** they 
31220 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20  return.  Hence, 
31230 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
31240 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63  tion can dealloc
31250 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79  ate or.** modify
31260 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20   the text after 
31270 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68  they return with
31280 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68  out harm..** ^Th
31290 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
312a0 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75  _error_code() fu
312b0 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74  nction changes t
312c0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  he error code.**
312d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
312e0 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20  ite as a result 
312f0 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61  of an error in a
31300 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20   function.  ^By 
31310 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
31320 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
31330 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20  LITE_ERROR.  ^A 
31340 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
31350 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
31360 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
31370 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31380 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20  rror16() resets 
31390 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74  the error code t
313a0 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a  o SQLITE_ERROR..
313b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
313c0 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67  e3_result_toobig
313d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
313e0 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
313f0 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20  row an error.** 
31400 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
31410 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
31420 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20   is too long to 
31430 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a  represent..**.**
31440 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
31450 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74  sult_nomem() int
31460 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
31470 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
31480 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
31490 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f  ting that a memo
314a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
314b0 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  iled..**.** ^The
314c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
314d0 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  int() interface 
314e0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
314f0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
31500 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
31510 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
31520 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69  be the 32-bit si
31530 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
31540 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
31550 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
31560 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31570 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20  _result_int64() 
31580 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
31590 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
315a0 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
315b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
315c0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
315d0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
315e0 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
315f0 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
31600 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
31610 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
31620 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65  sult_null() inte
31630 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
31640 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
31650 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
31660 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
31670 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a  on to be NULL..*
31680 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
31690 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c  3_result_text(),
316a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
316b0 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c  text16(),.** sql
316c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
316d0 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69  16le(), and sqli
316e0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
316f0 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6be() interfaces
31700 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75  .** set the retu
31710 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  rn value of the 
31720 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
31730 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
31740 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72  be.** a text str
31750 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70  ing which is rep
31760 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d  resented as UTF-
31770 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  8, UTF-16 native
31780 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20   byte order,.** 
31790 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e  UTF-16 little en
317a0 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20  dian, or UTF-16 
317b0 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70  big endian, resp
317c0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51  ectively..** ^SQ
317d0 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
317e0 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
317f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
31800 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
31810 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
31820 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31830 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
31840 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
31850 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
31860 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
31870 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
31880 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  s.** is negative
31890 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  , then SQLite ta
318a0 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20  kes result text 
318b0 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
318c0 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67  ameter.** throug
318d0 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
318e0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
318f0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
31900 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
31910 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
31920 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
31930 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
31940 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
31950 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
31960 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
31970 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
31980 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
31990 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
319a0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
319b0 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
319c0 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20  ion result.  If 
319d0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
319e0 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  r is non-negativ
319f0 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75  e, then it.** mu
31a00 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
31a10 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73  ffset into the s
31a20 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20  tring where the 
31a30 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
31a40 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69  ould.** appear i
31a50 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65  f the string whe
31a60 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65  re NUL terminate
31a70 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
31a80 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a  haracters occur.
31a90 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  ** in the string
31aa0 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65   at a byte offse
31ab0 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74  t that is less t
31ac0 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66  han the value of
31ad0 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61   the 3rd.** para
31ae0 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  meter, then the 
31af0 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
31b00 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d   will contain em
31b10 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20  bedded NULs and 
31b20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66  the.** result of
31b30 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65   expressions ope
31b40 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67  rating on string
31b50 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  s with embedded 
31b60 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
31b70 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  d..** ^If the 4t
31b80 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
31b90 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
31ba0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
31bb0 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
31bc0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
31bd0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
31be0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
31bf0 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75  calls that.** fu
31c00 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65  nction as the de
31c10 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
31c20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
31c30 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a  ult when it has.
31c40 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  ** finished usin
31c50 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
31c60 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
31c70 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
31c80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31c90 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f  xt* interfaces o
31ca0 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
31cb0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
31cc0 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
31cd0 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ant SQLITE_STATI
31ce0 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a  C, then SQLite.*
31cf0 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  * assumes that t
31d00 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
31d10 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e  result is in con
31d20 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20  stant space and 
31d30 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79  does not.** copy
31d40 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
31d50 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f  the parameter no
31d60 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63  r call a destruc
31d70 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65  tor on the conte
31d80 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61  nt.** when it ha
31d90 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
31da0 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
31db0 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
31dc0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
31dd0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
31de0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
31df0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
31e00 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
31e10 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
31e20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
31e30 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20  .** then SQLite 
31e40 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
31e50 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20  the result into 
31e60 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66  space obtained f
31e70 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  rom.** from [sql
31e80 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62  ite3_malloc()] b
31e90 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
31ea0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
31eb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
31ec0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
31ed0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  ts the result of
31ee0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
31ef0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
31f00 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70  tion to be a cop
31f10 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74  y the.** [unprot
31f20 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
31f30 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63  lue] object spec
31f40 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64  ified by the 2nd
31f50 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68   parameter.  ^Th
31f60 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  e.** sqlite3_res
31f70 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
31f80 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f  rface makes a co
31f90 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
31fa0 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20  e3_value].** so 
31fb0 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
31fc0 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69  3_value] specifi
31fd0 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ed in the parame
31fe0 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f  ter may change o
31ff0 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61  r.** be dealloca
32000 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
32010 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
32020 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74   returns without
32030 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72   harm..** ^A [pr
32040 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
32050 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61  value] object ma
32060 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64  y always be used
32070 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e   where an.** [un
32080 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
32090 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
320a0 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20  is required, so 
320b0 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f  either.** kind o
320c0 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
320d0 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20  ] object can be 
320e0 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69  used with this i
320f0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
32100 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  If these routine
32110 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  s are called fro
32120 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66  m within the dif
32130 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a  ferent thread.**
32140 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f   than the one co
32150 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70  ntaining the app
32160 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
32170 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72   function that r
32180 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b  eceived.** the [
32190 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
321a0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65   pointer, the re
321b0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
321c0 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ned..*/.void sql
321d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
321e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
321f0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
32200 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
32210 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
32220 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
32230 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32240 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64  *, double);.void
32250 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32260 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f  error(sqlite3_co
32270 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
32280 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  ar*, int);.void 
32290 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
322a0 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63  rror16(sqlite3_c
322b0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
322c0 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
322d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
322e0 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c  error_toobig(sql
322f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
32300 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32310 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
32320 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32330 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
32340 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
32350 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
32360 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
32370 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
32380 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
32390 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
323a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
323b0 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t64(sqlite3_cont
323c0 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ext*, sqlite3_in
323d0 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t64);.void sqlit
323e0 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73  e3_result_null(s
323f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
32400 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
32410 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74  esult_text(sqlit
32420 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
32430 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76  st char*, int, v
32440 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
32450 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32460 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ult_text16(sqlit
32470 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
32480 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
32490 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
324a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
324b0 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  ult_text16le(sql
324c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
324d0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
324e0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
324f0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
32500 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71  sult_text16be(sq
32510 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
32520 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
32530 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
32540 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
32550 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69  esult_value(sqli
32560 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
32570 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76  lite3_value*);.v
32580 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
32590 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  lt_zeroblob(sqli
325a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
325b0 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
325c0 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65  I3REF: Define Ne
325d0 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75  w Collating Sequ
325e0 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ences.**.** ^The
325f0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64  se functions add
32600 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64  , remove, or mod
32610 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e  ify a [collation
32620 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  ] associated.** 
32630 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
32640 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
32650 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20  pecified as the 
32660 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
32670 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
32680 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  of the collation
32690 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
326a0 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65  ng.** for sqlite
326b0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
326c0 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  on() and sqlite3
326d0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
326e0 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20  n_v2().** and a 
326f0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
32700 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
32710 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  er for sqlite3_c
32720 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
32730 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69  6()..** ^Collati
32740 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f  on names that co
32750 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f  mpare equal acco
32760 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65  rding to [sqlite
32770 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72  3_strnicmp()] ar
32780 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20  e.** considered 
32790 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e  to be the same n
327a0 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ame..**.** ^(The
327b0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
327c0 28 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20  (eTextRep) must 
327d0 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  be one of the co
327e0 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e  nstants:.** <ul>
327f0 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
32800 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _UTF8],.** <li> 
32810 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
32820 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
32830 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c  E_UTF16BE],.** <
32840 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
32850 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  6], or.** <li> [
32860 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
32870 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29  GNED]..** </ul>)
32880 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52  ^.** ^The eTextR
32890 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65  ep argument dete
328a0 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64  rmines the encod
328b0 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70  ing of strings p
328c0 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20  assed.** to the 
328d0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
328e0 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61  on callback, xCa
328f0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20  llback..** ^The 
32900 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61  [SQLITE_UTF16] a
32910 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  nd [SQLITE_UTF16
32920 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73  _ALIGNED] values
32930 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a   for eTextRep.**
32940 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74   force strings t
32950 6f 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20  o be UTF16 with 
32960 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
32970 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  r..** ^The [SQLI
32980 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
32990 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78  ] value for eTex
329a0 74 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69  tRep forces stri
329b0 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20  ngs to begin.** 
329c0 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20  on an even byte 
329d0 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e  address..**.** ^
329e0 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
329f0 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e  ent, pArg, is an
32a00 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
32a10 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  a pointer that i
32a20 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f  s passed.** thro
32a30 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
32a40 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
32a50 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
32a60 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ion callback..**
32a70 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
32a80 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61  rgument, xCallba
32a90 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ck, is a pointer
32aa0 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
32ab0 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e  g function..** ^
32ac0 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69  Multiple collati
32ad0 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e  ng functions can
32ae0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75   be registered u
32af0 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61  sing the same na
32b00 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64  me but.** with d
32b10 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65  ifferent eTextRe
32b20 70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64  p parameters and
32b30 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
32b40 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75   whichever.** fu
32b50 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
32b60 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
32b70 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f   of data transfo
32b80 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20  rmation..** ^If 
32b90 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72  the xCallback ar
32ba0 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74  gument is NULL t
32bb0 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  hen the collatin
32bc0 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a  g function is.**
32bd0 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e   deleted.  ^When
32be0 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66   all collating f
32bf0 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20  unctions having 
32c00 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72  the same name ar
32c10 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68  e deleted,.** th
32c20 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20  at collation is 
32c30 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65  no longer usable
32c40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c  ..**.** ^The col
32c50 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
32c60 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
32c70 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20  ked with a copy 
32c80 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20  of the pArg .** 
32c90 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
32ca0 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74   pointer and wit
32cb0 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e  h two strings in
32cc0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70   the encoding sp
32cd0 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
32ce0 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d  e eTextRep argum
32cf0 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74  ent.  The collat
32d00 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
32d10 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69  t return an.** i
32d20 6e 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e  nteger that is n
32d30 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f  egative, zero, o
32d40 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66  r positive.** if
32d50 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e   the first strin
32d60 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20  g is less than, 
32d70 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65  equal to, or gre
32d80 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65  ater than the se
32d90 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74  cond,.** respect
32da0 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74  ively.  A collat
32db0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
32dc0 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  t always return 
32dd0 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a  the same answer.
32de0 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d  ** given the sam
32df0 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77  e inputs.  If tw
32e00 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74  o or more collat
32e10 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ing functions ar
32e20 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20  e registered.** 
32e30 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c  to the same coll
32e40 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e  ation name (usin
32e50 67 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78  g different eTex
32e60 74 52 65 70 20 76 61 6c 75 65 73 29 20 74 68 65  tRep values) the
32e70 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69  n all.** must gi
32e80 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74  ve an equivalent
32e90 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76   answer when inv
32ea0 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69 76 61  oked with equiva
32eb0 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  lent strings..**
32ec0 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   The collating f
32ed0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65  unction must obe
32ee0 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  y the following 
32ef0 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61  properties for a
32f00 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c  ll.** strings A,
32f10 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a   B, and C:.**.**
32f20 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66   <ol>.** <li> If
32f30 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e   A==B then B==A.
32f40 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42  .** <li> If A==B
32f50 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41   and B==C then A
32f60 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  ==C..** <li> If 
32f70 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74  A&lt;B THEN B&gt
32f80 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  ;A..** <li> If A
32f90 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43  &lt;B and B&lt;C
32fa0 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a   then A&lt;C..**
32fb0 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </ol>.**.** If 
32fc0 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  a collating func
32fd0 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f  tion fails any o
32fe0 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73  f the above cons
32ff0 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74  traints and that
33000 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  .** collating fu
33010 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73  nction is  regis
33020 74 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20  tered and used, 
33030 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
33040 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69  r of SQLite.** i
33050 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
33060 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33070 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33080 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65  _v2() works like
33090 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
330a0 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77  collation().** w
330b0 69 74 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e  ith the addition
330c0 20 74 68 61 74 20 74 68 65 20 78 44 65 73 74 72   that the xDestr
330d0 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  oy callback is i
330e0 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77  nvoked on pArg w
330f0 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61  hen.** the colla
33100 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
33110 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f   deleted..** ^Co
33120 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
33130 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 77 68  s are deleted wh
33140 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72  en they are over
33150 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a  ridden by later.
33160 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ** calls to the 
33170 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69  collation creati
33180 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  on functions or 
33190 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74  when the.** [dat
331a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
331b0 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e  ] is closed usin
331c0 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  g [sqlite3_close
331d0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ()]..**.** ^The 
331e0 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63  xDestroy callbac
331f0 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20  k is <u>not</u> 
33200 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a  called if the .*
33210 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
33220 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
33230 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20  function fails. 
33240 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
33250 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  at invoke.** sql
33260 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
33270 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20  ation_v2() with 
33280 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74  a non-NULL xDest
33290 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  roy argument sho
332a0 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68  uld .** check th
332b0 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e  e return code an
332c0 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  d dispose of the
332d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
332e0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65  a pointer.** the
332f0 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72 20 74  mselves rather t
33300 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51  han expecting SQ
33310 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74  Lite to deal wit
33320 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a  h it for them..*
33330 2a 20 54 68 69 73 20 69 73 20 64 69 66 66 65 72  * This is differ
33340 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f  ent from every o
33350 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
33360 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f  rface.  The inco
33370 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73  nsistency .** is
33380 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74   unfortunate but
33390 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
333a0 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
333b0 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a  ing backwards .*
333c0 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  * compatibility.
333d0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
333e0 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61    [sqlite3_colla
333f0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61  tion_needed()] a
33400 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  nd [sqlite3_coll
33410 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
33420 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
33430 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
33440 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  on(.  sqlite3*, 
33450 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
33460 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
33470 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a  xtRep, .  void *
33480 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  pArg,.  int(*xCo
33490 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
334a0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
334b0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
334c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
334d0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
334e0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
334f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
33500 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
33510 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
33520 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
33530 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
33540 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
33550 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76  onst void*),.  v
33560 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
33570 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
33580 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
33590 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ation16(.  sqlit
335a0 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f  e3*, .  const vo
335b0 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74  id *zName,.  int
335c0 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
335d0 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
335e0 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
335f0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
33600 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
33610 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
33620 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20  3REF: Collation 
33630 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73  Needed Callbacks
33640 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64  .**.** ^To avoid
33650 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73   having to regis
33660 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f  ter all collatio
33670 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f  n sequences befo
33680 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  re a database.**
33690 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20   can be used, a 
336a0 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20  single callback 
336b0 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
336c0 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
336d0 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
336e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
336f0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
33700 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64  ver an undefined
33710 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
33720 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72  quence is requir
33730 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
33740 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65  e function is re
33750 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74  gistered using t
33760 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  he sqlite3_colla
33770 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50  tion_needed() AP
33780 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  I,.** then it is
33790 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65   passed the name
337a0 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63  s of undefined c
337b0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
337c0 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a  es as strings.**
337d0 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d   encoded in UTF-
337e0 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  8. ^If sqlite3_c
337f0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
33800 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20  6() is used,.** 
33810 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61  the names are pa
33820 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  ssed as UTF-16 i
33830 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65  n machine native
33840 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20   byte order..** 
33850 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65  ^A call to eithe
33860 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61  r function repla
33870 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e 67  ces the existing
33880 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65   collation-neede
33890 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  d callback..**.*
338a0 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c  * ^(When the cal
338b0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
338c0 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  , the first argu
338d0 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61  ment passed is a
338e0 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20   copy.** of the 
338f0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
33900 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  to sqlite3_colla
33910 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72  tion_needed() or
33920 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  .** sqlite3_coll
33930 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
33940 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  .  The second ar
33950 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61  gument is the da
33960 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
33970 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64  tion.  The third
33980 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
33990 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   of [SQLITE_UTF8
339a0 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
339b0 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  BE],.** or [SQLI
339c0 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64  TE_UTF16LE], ind
339d0 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74  icating the most
339e0 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20   desirable form 
339f0 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  of the collation
33a00 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e  .** sequence fun
33a10 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20  ction required. 
33a20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
33a30 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
33a40 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75  e of the.** requ
33a50 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ired collation s
33a60 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a  equence.)^.**.**
33a70 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
33a80 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65  nction should re
33a90 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72  gister the desir
33aa0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69  ed collation usi
33ab0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
33ac0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
33ad0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
33ae0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
33af0 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
33b00 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
33b10 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e  ion_v2()]..*/.in
33b20 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
33b30 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71  ion_needed(.  sq
33b40 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
33b50 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
33b60 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
33b70 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63  eTextRep,const c
33b80 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  har*).);.int sql
33b90 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
33ba0 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74  eeded16(.  sqlit
33bb0 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  e3*, .  void*,. 
33bc0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
33bd0 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
33be0 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  tRep,const void*
33bf0 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c  ).);..#ifdef SQL
33c00 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a  ITE_HAS_CODEC./*
33c10 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
33c20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79  key for an encry
33c30 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20  pted database.  
33c40 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f  This routine sho
33c50 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64  uld be.** called
33c60 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c   right after sql
33c70 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a  ite3_open()..**.
33c80 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
33c90 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
33ca0 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
33cb0 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
33cc0 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
33cd0 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
33ce0 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c  lite3_key(.  sql
33cf0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
33d00 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
33d10 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
33d20 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
33d30 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
33d40 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
33d50 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
33d60 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79  * Change the key
33d70 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   on an open data
33d80 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75  base.  If the cu
33d90 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69  rrent database i
33da0 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74  s not.** encrypt
33db0 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ed, this routine
33dc0 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74   will encrypt it
33dd0 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72  .  If pNew==0 or
33de0 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a   nNew==0, the.**
33df0 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63   database is dec
33e00 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  rypted..**.** Th
33e10 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
33e20 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
33e30 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
33e40 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
33e50 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
33e60 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
33e70 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  _rekey(.  sqlite
33e80 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
33e90 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
33ea0 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
33eb0 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
33ec0 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
33ed0 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65  ey     /* The ne
33ee0 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  w key */.);../*.
33ef0 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61  ** Specify the a
33f00 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f  ctivation key fo
33f10 72 20 61 20 53 45 45 20 64 61 74 61 62 61 73 65  r a SEE database
33f20 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63  .  Unless .** ac
33f30 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66  tivated, none of
33f40 20 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65   the SEE routine
33f50 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a  s will work..*/.
33f60 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74  void sqlite3_act
33f70 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e  ivate_see(.  con
33f80 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68  st char *zPassPh
33f90 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41  rase        /* A
33fa0 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65  ctivation phrase
33fb0 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23   */.);.#endif..#
33fc0 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41  ifdef SQLITE_ENA
33fd0 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20  BLE_CEROD./*.** 
33fe0 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69  Specify the acti
33ff0 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61  vation key for a
34000 20 43 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e   CEROD database.
34010 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74    Unless .** act
34020 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20  ivated, none of 
34030 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e  the CEROD routin
34040 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f  es will work..*/
34050 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63  .void sqlite3_ac
34060 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20  tivate_cerod(.  
34070 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73  const char *zPas
34080 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f  sPhrase        /
34090 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72  * Activation phr
340a0 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66  ase */.);.#endif
340b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
340c0 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74  : Suspend Execut
340d0 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20  ion For A Short 
340e0 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  Time.**.** The s
340f0 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66  qlite3_sleep() f
34100 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74  unction causes t
34110 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61  he current threa
34120 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65  d to suspend exe
34130 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74  cution.** for at
34140 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20   least a number 
34150 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
34160 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73  specified in its
34170 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
34180 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69  * If the operati
34190 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e  ng system does n
341a0 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70  ot support sleep
341b0 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a   requests with.*
341c0 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69  * millisecond ti
341d0 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74  me resolution, t
341e0 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c  hen the time wil
341f0 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20  l be rounded up 
34200 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73  to.** the neares
34210 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75  t second. The nu
34220 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
34230 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63  onds of sleep ac
34240 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73  tually.** reques
34250 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65  ted from the ope
34260 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73  rating system is
34270 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
34280 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65   ^SQLite impleme
34290 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61  nts this interfa
342a0 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68  ce by calling th
342b0 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65  e xSleep().** me
342c0 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
342d0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
342e0 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74 68  ] object.  If th
342f0 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
34300 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66 61  d.** of the defa
34310 75 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20 69  ult VFS is not i
34320 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72 65  mplemented corre
34330 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70  ctly, or not imp
34340 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61  lemented at.** a
34350 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ll, then the beh
34360 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
34370 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65 76  _sleep() may dev
34380 69 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64 65  iate from the de
34390 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20  scription.** in 
343a0 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
343b0 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20  agraphs..*/.int 
343c0 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e  sqlite3_sleep(in
343d0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
343e0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65  REF: Name Of The
343f0 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20   Folder Holding 
34400 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a  Temporary Files.
34410 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20  **.** ^(If this 
34420 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20  global variable 
34430 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
34440 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69   to a string whi
34450 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  ch is.** the nam
34460 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61  e of a folder (a
34470 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29  .k.a. directory)
34480 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f  , then all tempo
34490 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72  rary files.** cr
344a0 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20  eated by SQLite 
344b0 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69  when using a bui
344c0 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76  lt-in [sqlite3_v
344d0 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c  fs | VFS].** wil
344e0 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74  l be placed in t
344f0 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e  hat directory.)^
34500 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61    ^If this varia
34510 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ble.** is a NULL
34520 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
34530 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61  QLite performs a
34540 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61   search for an a
34550 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65  ppropriate.** te
34560 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72  mporary file dir
34570 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74  ectory..**.** It
34580 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
34590 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
345a0 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20  his variable in 
345b0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a  more than one.**
345c0 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d   thread at a tim
345d0 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61  e.  It is not sa
345e0 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
345f0 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
34600 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61  le.** if a [data
34610 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
34620 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61   is being used a
34630 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
34640 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a  in a separate.**
34650 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69   thread..** It i
34660 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20  s intended that 
34670 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65  this variable be
34680 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20   set once.** as 
34690 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20  part of process 
346a0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
346b0 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51  nd before any SQ
346c0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  Lite interface.*
346d0 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20  * routines have 
346e0 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20  been called and 
346f0 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
34700 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  le remain unchan
34710 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65  ged.** thereafte
34720 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74  r..**.** ^The [t
34730 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
34740 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20  ory pragma] may 
34750 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
34760 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a  able and cause.*
34770 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f  * it to point to
34780 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
34790 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
347a0 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65  alloc].  ^Furthe
347b0 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74  rmore,.** the [t
347c0 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
347d0 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61  ory pragma] alwa
347e0 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ys assumes that 
347f0 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68  any string.** th
34800 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
34810 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65   points to is he
34820 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74  ld in memory obt
34830 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
34840 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20  sqlite3_malloc] 
34850 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d  and the pragma m
34860 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72  ay attempt to fr
34870 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a  ee that memory.*
34880 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
34890 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65  _free]..** Hence
348a0 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62  , if this variab
348b0 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64  le is modified d
348c0 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20  irectly, either 
348d0 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  it should be.** 
348e0 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64  made NULL or mad
348f0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  e to point to me
34900 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
34910 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
34920 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74  oc].** or else t
34930 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74  he use of the [t
34940 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
34950 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75  ory pragma] shou
34960 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a  ld be avoided..*
34970 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  /.SQLITE_EXTERN 
34980 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65  char *sqlite3_te
34990 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f  mp_directory;../
349a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
349b0 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d  est For Auto-Com
349c0 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57  mit Mode.** KEYW
349d0 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69  ORDS: {autocommi
349e0 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54  t mode}.**.** ^T
349f0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
34a00 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65  utocommit() inte
34a10 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f  rface returns no
34a20 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72  n-zero or.** zer
34a30 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64  o if the given d
34a40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34a50 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20  on is or is not 
34a60 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  in autocommit mo
34a70 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  de,.** respectiv
34a80 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69  ely.  ^Autocommi
34a90 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20  t mode is on by 
34aa0 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74  default..** ^Aut
34ab0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
34ac0 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42  disabled by a [B
34ad0 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e  EGIN] statement.
34ae0 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20  .** ^Autocommit 
34af0 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c  mode is re-enabl
34b00 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d  ed by a [COMMIT]
34b10 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a   or [ROLLBACK]..
34b20 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e  **.** If certain
34b30 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73   kinds of errors
34b40 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74   occur on a stat
34b50 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d  ement within a m
34b60 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a  ulti-statement.*
34b70 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65  * transaction (e
34b80 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20  rrors including 
34b90 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b  [SQLITE_FULL], [
34ba0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a  SQLITE_IOERR],.*
34bb0 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
34bc0 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  , [SQLITE_BUSY],
34bd0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54   and [SQLITE_INT
34be0 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68  ERRUPT]) then th
34bf0 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  e.** transaction
34c00 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64   might be rolled
34c10 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
34c20 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77  lly.  The only w
34c30 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75  ay to.** find ou
34c40 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65  t whether SQLite
34c50 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
34c60 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74  olled back the t
34c70 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72  ransaction after
34c80 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20  .** an error is 
34c90 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63  to use this func
34ca0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  tion..**.** If a
34cb0 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68  nother thread ch
34cc0 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f  anges the autoco
34cd0 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74  mmit status of t
34ce0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
34cf0 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
34d00 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
34d10 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68  running, then th
34d20 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
34d30 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
34d40 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
34d50 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71  et_autocommit(sq
34d60 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
34d70 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54  CAPI3REF: Find T
34d80 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64  he Database Hand
34d90 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64  le Of A Prepared
34da0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
34db0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62   ^The sqlite3_db
34dc0 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63  _handle interfac
34dd0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64  e returns the [d
34de0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34df0 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f  on] handle.** to
34e00 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72   which a [prepar
34e10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65  ed statement] be
34e20 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 61  longs.  ^The [da
34e30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34e40 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  n].** returned b
34e50 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e  y sqlite3_db_han
34e60 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  dle is the same 
34e70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
34e80 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tion].** that wa
34e90 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
34ea0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
34eb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
34ec0 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69  v2()] call (or i
34ed0 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61  ts variants) tha
34ee0 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a  t was used to.**
34ef0 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74   create the stat
34f00 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72  ement in the fir
34f10 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c  st place..*/.sql
34f20 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62  ite3 *sqlite3_db
34f30 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
34f40 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
34f50 41 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20  API3REF: Return 
34f60 54 68 65 20 46 69 6c 65 6e 61 6d 65 20 46 6f 72  The Filename For
34f70 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e   A Database Conn
34f80 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ection.**.** ^Th
34f90 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c  e sqlite3_db_fil
34fa0 65 6e 61 6d 65 28 44 2c 4e 29 20 69 6e 74 65 72  ename(D,N) inter
34fb0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
34fc0 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 69 6c 65  ointer to a file
34fd0 6e 61 6d 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74  name.** associat
34fe0 65 64 20 77 69 74 68 20 64 61 74 61 62 61 73 65  ed with database
34ff0 20 4e 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e   N of connection
35000 20 44 2e 20 20 5e 54 68 65 20 6d 61 69 6e 20 64   D.  ^The main d
35010 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20  atabase file.** 
35020 68 61 73 20 74 68 65 20 6e 61 6d 65 20 22 6d 61  has the name "ma
35030 69 6e 22 2e 20 20 49 66 20 74 68 65 72 65 20 69  in".  If there i
35040 73 20 6e 6f 20 61 74 74 61 63 68 65 64 20 64 61  s no attached da
35050 74 61 62 61 73 65 20 4e 20 6f 6e 20 74 68 65 20  tabase N on the 
35060 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
35070 65 63 74 69 6f 6e 20 44 2c 20 6f 72 20 69 66 20  ection D, or if 
35080 64 61 74 61 62 61 73 65 20 4e 20 69 73 20 61 20  database N is a 
35090 74 65 6d 70 6f 72 61 72 79 20 6f 72 20 69 6e 2d  temporary or in-
350a0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 2c  memory database,
350b0 20 74 68 65 6e 0a 2a 2a 20 61 20 4e 55 4c 4c 20   then.** a NULL 
350c0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
350d0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
350e0 66 69 6c 65 6e 61 6d 65 20 72 65 74 75 72 6e 65  filename returne
350f0 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69  d by this functi
35100 6f 6e 20 69 73 20 74 68 65 20 6f 75 74 70 75 74  on is the output
35110 20 6f 66 20 74 68 65 0a 2a 2a 20 78 46 75 6c 6c   of the.** xFull
35120 50 61 74 68 6e 61 6d 65 20 6d 65 74 68 6f 64 20  Pathname method 
35130 6f 66 20 74 68 65 20 5b 56 46 53 5d 2e 20 20 5e  of the [VFS].  ^
35140 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
35150 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  the filename.** 
35160 77 69 6c 6c 20 62 65 20 61 6e 20 61 62 73 6f 6c  will be an absol
35170 75 74 65 20 70 61 74 68 6e 61 6d 65 2c 20 65 76  ute pathname, ev
35180 65 6e 20 69 66 20 74 68 65 20 66 69 6c 65 6e 61  en if the filena
35190 6d 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6f 70  me used.** to op
351a0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
351b0 6f 72 69 67 69 6e 61 6c 6c 79 20 77 61 73 20 61  originally was a
351c0 20 55 52 49 20 6f 72 20 72 65 6c 61 74 69 76 65   URI or relative
351d0 20 70 61 74 68 6e 61 6d 65 2e 0a 2a 2f 0a 63 6f   pathname..*/.co
351e0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
351f0 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 73 71  3_db_filename(sq
35200 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74  lite3 *db, const
35210 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b   char *zDbName);
35220 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35230 3a 20 44 65 74 65 72 6d 69 6e 65 20 69 66 20 61  : Determine if a
35240 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65 61   database is rea
35250 64 2d 6f 6e 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  d-only.**.** ^Th
35260 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 72 65 61  e sqlite3_db_rea
35270 64 6f 6e 6c 79 28 44 2c 4e 29 20 69 6e 74 65 72  donly(D,N) inter
35280 66 61 63 65 20 72 65 74 75 72 6e 73 20 31 20 69  face returns 1 i
35290 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 4e  f the database N
352a0 0a 2a 2a 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f  .** of connectio
352b0 6e 20 44 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79  n D is read-only
352c0 2c 20 30 20 69 66 20 69 74 20 69 73 20 72 65 61  , 0 if it is rea
352d0 64 2f 77 72 69 74 65 2c 20 6f 72 20 2d 31 20 69  d/write, or -1 i
352e0 66 20 4e 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68  f N is not.** th
352f0 65 20 6e 61 6d 65 20 6f 66 20 61 20 64 61 74 61  e name of a data
35300 62 61 73 65 20 6f 6e 20 63 6f 6e 6e 65 63 74 69  base on connecti
35310 6f 6e 20 44 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  on D..*/.int sql
35320 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79  ite3_db_readonly
35330 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f  (sqlite3 *db, co
35340 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d  nst char *zDbNam
35350 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
35360 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65  REF: Find the ne
35370 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  xt prepared stat
35380 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ement.**.** ^Thi
35390 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  s interface retu
353a0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
353b0 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61   the next [prepa
353c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
353d0 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73  fter.** pStmt as
353e0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
353f0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
35400 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49  ection] pDb.  ^I
35410 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a  f pStmt is NULL.
35420 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74  ** then this int
35430 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
35440 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
35450 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73  first prepared s
35460 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f  tatement.** asso
35470 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
35480 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35490 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f  ion pDb.  ^If no
354a0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
354b0 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73  ent.** satisfies
354c0 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20   the conditions 
354d0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
354e0 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c   it returns NULL
354f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74  ..**.** The [dat
35500 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35510 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61  ] pointer D in a
35520 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
35530 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44  ite3_next_stmt(D
35540 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20  ,S)] must refer 
35550 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62  to an open datab
35560 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
35570 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75  n and in particu
35580 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  lar must not be 
35590 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
355a0 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  */.sqlite3_stmt 
355b0 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  *sqlite3_next_st
355c0 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c  mt(sqlite3 *pDb,
355d0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70   sqlite3_stmt *p
355e0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
355f0 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41  PI3REF: Commit A
35600 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69  nd Rollback Noti
35610 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
35620 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ks.**.** ^The sq
35630 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
35640 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
35650 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
35660 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  ck.** function t
35670 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
35680 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74  never a transact
35690 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c  ion is [COMMIT |
356a0 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20   committed]..** 
356b0 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65  ^Any callback se
356c0 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
356d0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
356e0 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a  commit_hook().**
356f0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
35700 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35710 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
35720 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35730 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
35740 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
35750 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a  ters a callback.
35760 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ** function to b
35770 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
35780 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
35790 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20   is [ROLLBACK | 
357a0 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a  rolled back]..**
357b0 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73   ^Any callback s
357c0 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
357d0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
357e0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
357f0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
35800 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
35810 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
35820 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67  en..** ^The pArg
35830 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73   argument is pas
35840 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74  sed through to t
35850 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  he callback..** 
35860 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
35870 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f   on a commit hoo
35880 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  k function retur
35890 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20  ns non-zero,.** 
358a0 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20  then the commit 
358b0 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74  is converted int
358c0 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a  o a rollback..**
358d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
358e0 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43  _commit_hook(D,C
358f0 2c 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ,P) and sqlite3_
35900 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c  rollback_hook(D,
35910 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  C,P) functions.*
35920 2a 20 72 65 74 75 72 6e 20 74 68 65 20 50 20 61  * return the P a
35930 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65  rgument from the
35940 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f   previous call o
35950 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
35960 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61  ion.** on the sa
35970 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
35980 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e  nection] D, or N
35990 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66  ULL for.** the f
359a0 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61  irst call for ea
359b0 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44  ch function on D
359c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6d 6d  ..**.** The comm
359d0 69 74 20 61 6e 64 20 72 6f 6c 6c 62 61 63 6b 20  it and rollback 
359e0 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 73 20 61  hook callbacks a
359f0 72 65 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  re not reentrant
35a00 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  ..** The callbac
35a10 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  k implementation
35a20 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
35a30 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
35a40 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
35a50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35a60 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
35a70 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e  he callback.  An
35a80 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20  y actions.** to 
35a90 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
35aa0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
35ab0 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20  ust be deferred 
35ac0 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a  until after the.
35ad0 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66  ** completion of
35ae0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
35af0 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  ep()] call that 
35b00 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f  triggered the co
35b10 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62  mmit.** or rollb
35b20 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20  ack hook in the 
35b30 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20  first place..** 
35b40 4e 6f 74 65 20 74 68 61 74 20 72 75 6e 6e 69 6e  Note that runnin
35b50 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 20  g any other SQL 
35b60 73 74 61 74 65 6d 65 6e 74 73 2c 20 69 6e 63 6c  statements, incl
35b70 75 64 69 6e 67 20 53 45 4c 45 43 54 20 73 74 61  uding SELECT sta
35b80 74 65 6d 65 6e 74 73 2c 0a 2a 2a 20 6f 72 20 6d  tements,.** or m
35b90 65 72 65 6c 79 20 63 61 6c 6c 69 6e 67 20 5b 73  erely calling [s
35ba0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
35bb0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
35bc0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 6d  3_step()] will m
35bd0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
35be0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35bf0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
35c00 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
35c10 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
35c20 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72  .**.** ^Register
35c30 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74  ing a NULL funct
35c40 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65  ion disables the
35c50 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
35c60 20 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69   ^When the commi
35c70 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20  t hook callback 
35c80 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
35c90 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49  zero, the [COMMI
35ca0 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20  T].** operation 
35cb0 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f  is allowed to co
35cc0 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e  ntinue normally.
35cd0 20 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74    ^If the commit
35ce0 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73   hook.** returns
35cf0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
35d00 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20  the [COMMIT] is 
35d10 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
35d20 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20   [ROLLBACK]..** 
35d30 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f  ^The rollback ho
35d40 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ok is invoked on
35d50 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74   a rollback that
35d60 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20   results from a 
35d70 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72  commit.** hook r
35d80 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72  eturning non-zer
35d90 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f  o, just as it wo
35da0 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 20  uld be with any 
35db0 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a  other rollback..
35dc0 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
35dd0 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
35de0 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69  API, a transacti
35df0 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61  on is said to ha
35e00 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65  ve been.** rolle
35e10 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70  d back if an exp
35e20 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22  licit "ROLLBACK"
35e30 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78   statement is ex
35e40 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e  ecuted, or.** an
35e50 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72   error or constr
35e60 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69  aint causes an i
35e70 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b  mplicit rollback
35e80 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54   to occur..** ^T
35e90 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c  he rollback call
35ea0 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  back is not invo
35eb0 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63  ked if a transac
35ec0 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d  tion is.** autom
35ed0 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
35ee0 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65  back because the
35ef0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
35f00 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
35f10 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
35f20 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61  he [sqlite3_upda
35f30 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72  te_hook()] inter
35f40 66 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  face..*/.void *s
35f50 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
35f60 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ok(sqlite3*, int
35f70 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
35f80 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  *);.void *sqlite
35f90 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
35fa0 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
35fb0 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a  )(void *), void*
35fc0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
35fd0 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20  EF: Data Change 
35fe0 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c  Notification Cal
35ff0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
36000 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  e sqlite3_update
36010 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
36020 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
36030 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
36040 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ** with the [dat
36050 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36060 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  ] identified by 
36070 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
36080 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f  nt.** to be invo
36090 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72  ked whenever a r
360a0 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69  ow is updated, i
360b0 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
360c0 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c  ed..** ^Any call
360d0 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
360e0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74  evious call to t
360f0 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
36100 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
36110 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36120 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
36130 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
36140 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
36150 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
36160 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b  unction to invok
36170 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20  e when a.** row 
36180 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
36190 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
361a0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
361b0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
361c0 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
361d0 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61  y of the third a
361e0 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71  rgument.** to sq
361f0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
36200 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63  k()..** ^The sec
36210 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67  ond callback arg
36220 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
36230 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c  [SQLITE_INSERT],
36240 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
36250 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
36260 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69  UPDATE], dependi
36270 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74  ng on the operat
36280 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20  ion that caused 
36290 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
362a0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a  to be invoked..*
362b0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64  * ^The third and
362c0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
362d0 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  s to the callbac
362e0 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65  k contain pointe
362f0 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  rs to the.** dat
36300 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20  abase and table 
36310 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  name containing 
36320 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77  the affected row
36330 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20  ..** ^The final 
36340 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74  callback paramet
36350 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64  er is the [rowid
36360 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a  ] of the row..**
36370 20 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66   ^In the case of
36380 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73   an update, this
36390 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20   is the [rowid] 
363a0 61 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65  after the update
363b0 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a   takes place..**
363c0 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65  .** ^(The update
363d0 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76   hook is not inv
363e0 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e  oked when intern
363f0 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73  al system tables
36400 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   are.** modified
36410 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61   (i.e. sqlite_ma
36420 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f  ster and sqlite_
36430 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a  sequence).)^.**.
36440 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65  ** ^In the curre
36450 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
36460 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  n, the update ho
36470 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76  ok.** is not inv
36480 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63  oked when duplic
36490 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64  ation rows are d
364a0 65 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f  eleted because o
364b0 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46  f an.** [ON CONF
364c0 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49  LICT | ON CONFLI
364d0 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75  CT REPLACE] clau
364e0 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65  se.  ^Nor is the
364f0 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20   update hook.** 
36500 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77  invoked when row
36510 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73  s are deleted us
36520 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74  ing the [truncat
36530 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e  e optimization].
36540 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f  .** The exceptio
36550 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68  ns defined in th
36560 69 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67  is paragraph mig
36570 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ht change in a f
36580 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
36590 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
365a0 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f  * The update hoo
365b0 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  k implementation
365c0 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
365d0 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
365e0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
365f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36600 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
36610 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20  he update hook. 
36620 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20   Any actions.** 
36630 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  to modify the da
36640 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36650 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72  n must be deferr
36660 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74  ed until after t
36670 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e  he.** completion
36680 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
36690 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68  _step()] call th
366a0 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
366b0 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a   update hook..**
366c0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
366d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
366e0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
366f0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
36700 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
36710 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
36720 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
36730 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
36740 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
36750 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36760 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44  e3_update_hook(D
36770 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a  ,C,P) function.*
36780 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20  * returns the P 
36790 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68  argument from th
367a0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a  e previous call.
367b0 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ** on the same [
367c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
367d0 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20  ion] D, or NULL 
367e0 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74  for.** the first
367f0 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a   call on D..**.*
36800 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
36810 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
36820 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ook()] and [sqli
36830 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
36840 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  k()].** interfac
36850 65 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  es..*/.void *sql
36860 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
36870 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
36880 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c   void(*)(void *,
36890 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20  int ,char const 
368a0 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73  *,char const *,s
368b0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20  qlite3_int64),. 
368c0 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a   void*.);../*.**
368d0 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
368e0 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61  e Or Disable Sha
368f0 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a  red Pager Cache.
36900 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
36910 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
36920 64 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61  disables the sha
36930 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61  ring of the data
36940 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e  base cache.** an
36950 64 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74  d schema data st
36960 72 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e  ructures between
36970 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36980 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69  ction | connecti
36990 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73  ons].** to the s
369a0 61 6d 65 20 64 61 74 61 62 61 73 65 2e 20 53 68  ame database. Sh
369b0 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64  aring is enabled
369c0 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   if the argument
369d0 20 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20   is true.** and 
369e0 64 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20  disabled if the 
369f0 61 72 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73  argument is fals
36a00 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68  e.)^.**.** ^Cach
36a10 65 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61  e sharing is ena
36a20 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65  bled and disable
36a30 64 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20  d for an entire 
36a40 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73  process..** This
36a50 20 69 73 20 61 20 63 68 61 6e 67 65 20 61 73 20   is a change as 
36a60 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
36a70 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f  n 3.5.0. In prio
36a80 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
36a90 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67  Lite,.** sharing
36aa0 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20   was enabled or 
36ab0 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63  disabled for eac
36ac0 68 20 74 68 72 65 61 64 20 73 65 70 61 72 61 74  h thread separat
36ad0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ely..**.** ^(The
36ae0 20 63 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d   cache sharing m
36af0 6f 64 65 20 73 65 74 20 62 79 20 74 68 69 73 20  ode set by this 
36b00 69 6e 74 65 72 66 61 63 65 20 65 66 66 65 63 74  interface effect
36b10 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  s all subsequent
36b20 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  .** calls to [sq
36b30 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
36b40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
36b50 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
36b60 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45  _open16()]..** E
36b70 78 69 73 74 69 6e 67 20 64 61 74 61 62 61 73 65  xisting database
36b80 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e   connections con
36b90 74 69 6e 75 65 20 75 73 65 20 74 68 65 20 73 68  tinue use the sh
36ba0 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68  aring mode.** th
36bb0 61 74 20 77 61 73 20 69 6e 20 65 66 66 65 63 74  at was in effect
36bc0 20 61 74 20 74 68 65 20 74 69 6d 65 20 74 68 65   at the time the
36bd0 79 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 29 5e  y were opened.)^
36be0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
36bf0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
36c00 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61  QLITE_OK] if sha
36c10 72 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e  red cache was en
36c20 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
36c30 64 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  d.** successfull
36c40 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f  y.  An [error co
36c50 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  de] is returned 
36c60 6f 74 68 65 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a  otherwise.)^.**.
36c70 2a 2a 20 5e 53 68 61 72 65 64 20 63 61 63 68 65  ** ^Shared cache
36c80 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
36c90 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69  default. But thi
36ca0 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  s might change i
36cb0 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65  n.** future rele
36cc0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ases of SQLite. 
36cd0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
36ce0 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68  at care about sh
36cf0 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65  ared.** cache se
36d00 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74  tting should set
36d10 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a   it explicitly..
36d20 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20  **.** See Also: 
36d30 20 5b 53 51 4c 69 74 65 20 53 68 61 72 65 64 2d   [SQLite Shared-
36d40 43 61 63 68 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 69  Cache Mode].*/.i
36d50 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  nt sqlite3_enabl
36d60 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 69  e_shared_cache(i
36d70 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
36d80 33 52 45 46 3a 20 41 74 74 65 6d 70 74 20 54 6f  3REF: Attempt To
36d90 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72   Free Heap Memor
36da0 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
36db0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
36dc0 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20  ory() interface 
36dd0 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65  attempts to free
36de0 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 68   N bytes.** of h
36df0 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65  eap memory by de
36e00 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65  allocating non-e
36e10 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 20  ssential memory 
36e20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20 68  allocations.** h
36e30 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62  eld by the datab
36e40 61 73 65 20 6c 69 62 72 61 72 79 2e 20 20 20 4d  ase library.   M
36e50 65 6d 6f 72 79 20 75 73 65 64 20 74 6f 20 63 61  emory used to ca
36e60 63 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  che database.** 
36e70 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65  pages to improve
36e80 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20   performance is 
36e90 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f  an example of no
36ea0 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f  n-essential memo
36eb0 72 79 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f  ry..** ^sqlite3_
36ec0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
36ed0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
36ee0 62 65 72 20 6f 66 20 62 79 74 65 73 20 61 63 74  ber of bytes act
36ef0 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a 20  ually freed,.** 
36f00 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d  which might be m
36f10 6f 72 65 20 6f 72 20 6c 65 73 73 20 74 68 61 6e  ore or less than
36f20 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75   the amount requ
36f30 65 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ested..** ^The s
36f40 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
36f50 65 6d 6f 72 79 28 29 20 72 6f 75 74 69 6e 65 20  emory() routine 
36f60 69 73 20 61 20 6e 6f 2d 6f 70 20 72 65 74 75 72  is a no-op retur
36f70 6e 69 6e 67 20 7a 65 72 6f 0a 2a 2a 20 69 66 20  ning zero.** if 
36f80 53 51 4c 69 74 65 20 69 73 20 6e 6f 74 20 63 6f  SQLite is not co
36f90 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
36fa0 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52  ITE_ENABLE_MEMOR
36fb0 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a  Y_MANAGEMENT]..*
36fc0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
36fd0 73 71 6c 69 74 65 33 5f 64 62 5f 72 65 6c 65 61  sqlite3_db_relea
36fe0 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2f 0a  se_memory()].*/.
36ff0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  int sqlite3_rele
37000 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b  ase_memory(int);
37010 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37020 3a 20 46 72 65 65 20 4d 65 6d 6f 72 79 20 55 73  : Free Memory Us
37030 65 64 20 42 79 20 41 20 44 61 74 61 62 61 73 65  ed By A Database
37040 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a   Connection.**.*
37050 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
37060 62 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  b_release_memory
37070 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  (D) interface at
37080 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20 61  tempts to free a
37090 73 20 6d 75 63 68 20 68 65 61 70 0a 2a 2a 20 6d  s much heap.** m
370a0 65 6d 6f 72 79 20 61 73 20 70 6f 73 73 69 62 6c  emory as possibl
370b0 65 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20  e from database 
370c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 55 6e  connection D. Un
370d0 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  like the.** [sql
370e0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
370f0 6f 72 79 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ory()] interface
37100 2c 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  , this interface
37110 20 69 73 20 65 66 66 65 63 74 20 65 76 65 6e 0a   is effect even.
37120 2a 2a 20 77 68 65 6e 20 74 68 65 6e 20 5b 53 51  ** when then [SQ
37130 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f  LITE_ENABLE_MEMO
37140 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 20 63  RY_MANAGEMENT] c
37150 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
37160 6f 6e 20 69 73 0a 2a 2a 20 6f 6d 69 74 74 65 64  on is.** omitted
37170 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
37180 3a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  : [sqlite3_relea
37190 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2f 0a  se_memory()].*/.
371a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 72  int sqlite3_db_r
371b0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 73 71  elease_memory(sq
371c0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
371d0 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65  CAPI3REF: Impose
371e0 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70   A Limit On Heap
371f0 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65   Size.**.** ^The
37200 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65   sqlite3_soft_he
37210 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 69 6e 74  ap_limit64() int
37220 65 72 66 61 63 65 20 73 65 74 73 20 61 6e 64 2f  erface sets and/
37230 6f 72 20 71 75 65 72 69 65 73 20 74 68 65 0a 2a  or queries the.*
37240 2a 20 73 6f 66 74 20 6c 69 6d 69 74 20 6f 6e 20  * soft limit on 
37250 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65  the amount of he
37260 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d  ap memory that m
37270 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20  ay be allocated 
37280 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e 53  by SQLite..** ^S
37290 51 4c 69 74 65 20 73 74 72 69 76 65 73 20 74 6f  QLite strives to
372a0 20 6b 65 65 70 20 68 65 61 70 20 6d 65 6d 6f 72   keep heap memor
372b0 79 20 75 74 69 6c 69 7a 61 74 69 6f 6e 20 62 65  y utilization be
372c0 6c 6f 77 20 74 68 65 20 73 6f 66 74 20 68 65 61  low the soft hea
372d0 70 0a 2a 2a 20 6c 69 6d 69 74 20 62 79 20 72 65  p.** limit by re
372e0 64 75 63 69 6e 67 20 74 68 65 20 6e 75 6d 62 65  ducing the numbe
372f0 72 20 6f 66 20 70 61 67 65 73 20 68 65 6c 64 20  r of pages held 
37300 69 6e 20 74 68 65 20 70 61 67 65 20 63 61 63 68  in the page cach
37310 65 0a 2a 2a 20 61 73 20 68 65 61 70 20 6d 65 6d  e.** as heap mem
37320 6f 72 79 20 75 73 61 67 65 73 20 61 70 70 72 6f  ory usages appro
37330 61 63 68 65 73 20 74 68 65 20 6c 69 6d 69 74 2e  aches the limit.
37340 0a 2a 2a 20 5e 54 68 65 20 73 6f 66 74 20 68 65  .** ^The soft he
37350 61 70 20 6c 69 6d 69 74 20 69 73 20 22 73 6f 66  ap limit is "sof
37360 74 22 20 62 65 63 61 75 73 65 20 65 76 65 6e 20  t" because even 
37370 74 68 6f 75 67 68 20 53 51 4c 69 74 65 20 73 74  though SQLite st
37380 72 69 76 65 73 20 74 6f 20 73 74 61 79 0a 2a 2a  rives to stay.**
37390 20 62 65 6c 6f 77 20 74 68 65 20 6c 69 6d 69 74   below the limit
373a0 2c 20 69 74 20 77 69 6c 6c 20 65 78 63 65 65 64  , it will exceed
373b0 20 74 68 65 20 6c 69 6d 69 74 20 72 61 74 68 65   the limit rathe
373c0 72 20 74 68 61 6e 20 67 65 6e 65 72 61 74 65 0a  r than generate.
373d0 2a 2a 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f  ** an [SQLITE_NO
373e0 4d 45 4d 5d 20 65 72 72 6f 72 2e 20 20 49 6e 20  MEM] error.  In 
373f0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
37400 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
37410 20 0a 2a 2a 20 69 73 20 61 64 76 69 73 6f 72 79   .** is advisory
37420 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   only..**.** ^Th
37430 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
37440 72 6f 6d 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  rom sqlite3_soft
37450 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20  _heap_limit64() 
37460 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a  is the size of.*
37470 2a 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  * the soft heap 
37480 6c 69 6d 69 74 20 70 72 69 6f 72 20 74 6f 20 74  limit prior to t
37490 68 65 20 63 61 6c 6c 2c 20 6f 72 20 6e 65 67 61  he call, or nega
374a0 74 69 76 65 20 69 6e 20 74 68 65 20 63 61 73 65  tive in the case
374b0 20 6f 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e   of an.** error.
374c0 20 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65    ^If the argume
374d0 6e 74 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65  nt N is negative
374e0 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e  .** then no chan
374f0 67 65 20 69 73 20 6d 61 64 65 20 74 6f 20 74 68  ge is made to th
37500 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
37510 74 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  t.  Hence, the c
37520 75 72 72 65 6e 74 0a 2a 2a 20 73 69 7a 65 20 6f  urrent.** size o
37530 66 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  f the soft heap 
37540 6c 69 6d 69 74 20 63 61 6e 20 62 65 20 64 65 74  limit can be det
37550 65 72 6d 69 6e 65 64 20 62 79 20 69 6e 76 6f 6b  ermined by invok
37560 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
37570 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
37580 28 29 20 77 69 74 68 20 61 20 6e 65 67 61 74 69  () with a negati
37590 76 65 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  ve argument..**.
375a0 2a 2a 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d  ** ^If the argum
375b0 65 6e 74 20 4e 20 69 73 20 7a 65 72 6f 20 74 68  ent N is zero th
375c0 65 6e 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  en the soft heap
375d0 20 6c 69 6d 69 74 20 69 73 20 64 69 73 61 62 6c   limit is disabl
375e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ed..**.** ^(The 
375f0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
37600 69 73 20 6e 6f 74 20 65 6e 66 6f 72 63 65 64 20  is not enforced 
37610 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  in the current i
37620 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
37630 20 69 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   if one or more 
37640 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e  of following con
37650 64 69 74 69 6f 6e 73 20 61 72 65 20 74 72 75 65  ditions are true
37660 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
37670 3c 6c 69 3e 20 54 68 65 20 73 6f 66 74 20 68 65  <li> The soft he
37680 61 70 20 6c 69 6d 69 74 20 69 73 20 73 65 74 20  ap limit is set 
37690 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e  to zero..** <li>
376a0 20 4d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69   Memory accounti
376b0 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 20 75  ng is disabled u
376c0 73 69 6e 67 20 61 20 63 6f 6d 62 69 6e 61 74 69  sing a combinati
376d0 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  on of the.**    
376e0 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69    [sqlite3_confi
376f0 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
37700 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c 2e 2e 2e  G_MEMSTATUS],...
37710 29 20 73 74 61 72 74 2d 74 69 6d 65 20 6f 70 74  ) start-time opt
37720 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ion and.**      
37730 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  the [SQLITE_DEFA
37740 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63  ULT_MEMSTATUS] c
37750 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
37760 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 41 6e 20 61  on..** <li> An a
37770 6c 74 65 72 6e 61 74 69 76 65 20 70 61 67 65 20  lternative page 
37780 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
37790 74 69 6f 6e 20 69 73 20 73 70 65 63 69 66 69 65  tion is specifie
377a0 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
377b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
377c0 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
377d0 50 43 41 43 48 45 32 5d 2c 2e 2e 2e 29 2e 0a 2a  PCACHE2],...)..*
377e0 2a 20 3c 6c 69 3e 20 54 68 65 20 70 61 67 65 20  * <li> The page 
377f0 63 61 63 68 65 20 61 6c 6c 6f 63 61 74 65 73 20  cache allocates 
37800 66 72 6f 6d 20 69 74 73 20 6f 77 6e 20 6d 65 6d  from its own mem
37810 6f 72 79 20 70 6f 6f 6c 20 73 75 70 70 6c 69 65  ory pool supplie
37820 64 0a 2a 2a 20 20 20 20 20 20 62 79 20 5b 73 71  d.**      by [sq
37830 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
37840 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
37850 45 43 41 43 48 45 5d 2c 2e 2e 2e 29 20 72 61 74  ECACHE],...) rat
37860 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  her than.**     
37870 20 66 72 6f 6d 20 74 68 65 20 68 65 61 70 2e 0a   from the heap..
37880 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
37890 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20   Beginning with 
378a0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
378b0 2e 37 2e 33 2c 20 74 68 65 20 73 6f 66 74 20 68  .7.3, the soft h
378c0 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e 66  eap limit is enf
378d0 6f 72 63 65 64 0a 2a 2a 20 72 65 67 61 72 64 6c  orced.** regardl
378e0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
378f0 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54  r not the [SQLIT
37900 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f  E_ENABLE_MEMORY_
37910 4d 41 4e 41 47 45 4d 45 4e 54 5d 0a 2a 2a 20 63  MANAGEMENT].** c
37920 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
37930 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  on is invoked.  
37940 57 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41  With [SQLITE_ENA
37950 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47  BLE_MEMORY_MANAG
37960 45 4d 45 4e 54 5d 2c 0a 2a 2a 20 74 68 65 20 73  EMENT],.** the s
37970 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
37980 73 20 65 6e 66 6f 72 63 65 64 20 6f 6e 20 65 76  s enforced on ev
37990 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
379a0 61 74 69 6f 6e 2e 20 20 57 69 74 68 6f 75 74 0a  ation.  Without.
379b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
379c0 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d  E_MEMORY_MANAGEM
379d0 45 4e 54 5d 2c 20 74 68 65 20 73 6f 66 74 20 68  ENT], the soft h
379e0 65 61 70 20 6c 69 6d 69 74 20 69 73 20 6f 6e 6c  eap limit is onl
379f0 79 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20 77 68  y enforced.** wh
37a00 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c  en memory is all
37a10 6f 63 61 74 65 64 20 62 79 20 74 68 65 20 70 61  ocated by the pa
37a20 67 65 20 63 61 63 68 65 2e 20 20 54 65 73 74 69  ge cache.  Testi
37a30 6e 67 20 73 75 67 67 65 73 74 73 20 74 68 61 74  ng suggests that
37a40 20 62 65 63 61 75 73 65 0a 2a 2a 20 74 68 65 20   because.** the 
37a50 70 61 67 65 20 63 61 63 68 65 20 69 73 20 74 68  page cache is th
37a60 65 20 70 72 65 64 6f 6d 69 6e 61 74 65 20 6d 65  e predominate me
37a70 6d 6f 72 79 20 75 73 65 72 20 69 6e 20 53 51 4c  mory user in SQL
37a80 69 74 65 2c 20 6d 6f 73 74 0a 2a 2a 20 61 70 70  ite, most.** app
37a90 6c 69 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 61  lications will a
37aa0 63 68 69 65 76 65 20 61 64 65 71 75 61 74 65 20  chieve adequate 
37ab0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
37ac0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 77 69 74 68  enforcement with
37ad0 6f 75 74 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  out.** the use o
37ae0 66 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  f [SQLITE_ENABLE
37af0 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45  _MEMORY_MANAGEME
37b00 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  NT]..**.** The c
37b10 69 72 63 75 6d 73 74 61 6e 63 65 73 20 75 6e 64  ircumstances und
37b20 65 72 20 77 68 69 63 68 20 53 51 4c 69 74 65 20  er which SQLite 
37b30 77 69 6c 6c 20 65 6e 66 6f 72 63 65 20 74 68 65  will enforce the
37b40 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
37b50 20 6d 61 79 0a 2a 2a 20 63 68 61 6e 67 65 73 20   may.** changes 
37b60 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
37b70 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  es of SQLite..*/
37b80 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
37b90 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
37ba0 5f 6c 69 6d 69 74 36 34 28 73 71 6c 69 74 65 33  _limit64(sqlite3
37bb0 5f 69 6e 74 36 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a  _int64 N);../*.*
37bc0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72  * CAPI3REF: Depr
37bd0 65 63 61 74 65 64 20 53 6f 66 74 20 48 65 61 70  ecated Soft Heap
37be0 20 4c 69 6d 69 74 20 49 6e 74 65 72 66 61 63 65   Limit Interface
37bf0 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a  .** DEPRECATED.*
37c00 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 64  *.** This is a d
37c10 65 70 72 65 63 61 74 65 64 20 76 65 72 73 69 6f  eprecated versio
37c20 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
37c30 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
37c40 74 36 34 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  t64()].** interf
37c50 61 63 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ace.  This routi
37c60 6e 65 20 69 73 20 70 72 6f 76 69 64 65 64 20 66  ne is provided f
37c70 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
37c80 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 6f  mpatibility.** o
37c90 6e 6c 79 2e 20 20 41 6c 6c 20 6e 65 77 20 61 70  nly.  All new ap
37ca0 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
37cb0 64 20 75 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71  d use the.** [sq
37cc0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
37cd0 6c 69 6d 69 74 36 34 28 29 5d 20 69 6e 74 65 72  limit64()] inter
37ce0 66 61 63 65 20 72 61 74 68 65 72 20 74 68 61 6e  face rather than
37cf0 20 74 68 69 73 20 6f 6e 65 2e 0a 2a 2f 0a 53 51   this one..*/.SQ
37d00 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
37d10 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66  void sqlite3_sof
37d20 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74  t_heap_limit(int
37d30 20 4e 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   N);.../*.** CAP
37d40 49 33 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d  I3REF: Extract M
37d50 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20  etadata About A 
37d60 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c  Column Of A Tabl
37d70 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  e.**.** ^This ro
37d80 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d 65  utine returns me
37d90 74 61 64 61 74 61 20 61 62 6f 75 74 20 61 20 73  tadata about a s
37da0 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f  pecific column o
37db0 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  f a specific.** 
37dc0 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61  database table a
37dd0 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20  ccessible using 
37de0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
37df0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
37e00 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68  .** passed as th
37e10 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e  e first function
37e20 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
37e30 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20   ^The column is 
37e40 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
37e50 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20  e second, third 
37e60 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d  and fourth param
37e70 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73  eters to.** this
37e80 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 20   function. ^The 
37e90 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
37ea0 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e   is either the n
37eb0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
37ec0 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61  ase.** (i.e. "ma
37ed0 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f 72 20  in", "temp", or 
37ee0 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61  an attached data
37ef0 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67  base) containing
37f00 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a   the specified.*
37f10 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e  * table or NULL.
37f20 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c   ^If it is NULL,
37f30 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68   then all attach
37f40 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72 65  ed databases are
37f50 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72   searched.** for
37f60 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67   the table using
37f70 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69   the same algori
37f80 74 68 6d 20 75 73 65 64 20 62 79 20 74 68 65 20  thm used by the 
37f90 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
37fa0 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e  to.** resolve un
37fb0 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20  qualified table 
37fc0 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a  references..**.*
37fd0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64  * ^The third and
37fe0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
37ff0 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
38000 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c  ion are the tabl
38010 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  e and column.** 
38020 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69  name of the desi
38030 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70  red column, resp
38040 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65  ectively. Neithe
38050 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d  r of these param
38060 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20  eters.** may be 
38070 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74  NULL..**.** ^Met
38080 61 64 61 74 61 20 69 73 20 72 65 74 75 72 6e 65  adata is returne
38090 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20  d by writing to 
380a0 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74  the memory locat
380b0 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20 74  ions passed as t
380c0 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75  he 5th.** and su
380d0 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74  bsequent paramet
380e0 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ers to this func
380f0 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 68  tion. ^Any of th
38100 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d 61  ese arguments ma
38110 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e  y be.** NULL, in
38120 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
38130 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c  corresponding el
38140 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 74  ement of metadat
38150 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  a is omitted..**
38160 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74  .** ^(<blockquot
38170 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
38180 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
38190 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72 20 3c  <th> Parameter <
381a0 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54 79  th> Output<br>Ty
381b0 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72 69 70  pe <th>  Descrip
381c0 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  tion.**.** <tr><
381d0 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e  td> 5th <td> con
381e0 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 44 61  st char* <td> Da
381f0 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c  ta type.** <tr><
38200 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e  td> 6th <td> con
38210 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61  st char* <td> Na
38220 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20 63 6f  me of default co
38230 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
38240 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68  .** <tr><td> 7th
38250 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20   <td> int       
38260 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63    <td> True if c
38270 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20  olumn has a NOT 
38280 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a  NULL constraint.
38290 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20  ** <tr><td> 8th 
382a0 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20  <td> int        
382b0 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f   <td> True if co
382c0 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20  lumn is part of 
382d0 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a  the PRIMARY KEY.
382e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20  ** <tr><td> 9th 
382f0 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20  <td> int        
38300 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f   <td> True if co
38310 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43  lumn is [AUTOINC
38320 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62  REMENT].** </tab
38330 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
38340 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
38350 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64  e memory pointed
38360 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61   to by the chara
38370 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65  cter pointers re
38380 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a  turned for the.*
38390 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79  * declaration ty
383a0 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e  pe and collation
383b0 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c   sequence is val
383c0 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68  id only until th
383d0 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74  e next.** call t
383e0 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50 49  o any SQLite API
383f0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
38400 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
38410 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75  ed table is actu
38420 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20  ally a view, an 
38430 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
38440 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
38450 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65  ^If the specifie
38460 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77  d column is "row
38470 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f  id", "oid" or "_
38480 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a  rowid_" and an.*
38490 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  * [INTEGER PRIMA
384a0 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68  RY KEY] column h
384b0 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74  as been explicit
384c0 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65  ly declared, the
384d0 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20  n the output.** 
384e0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73  parameters are s
384f0 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69  et for the expli
38500 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
38510 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68 65 72  olumn. ^(If ther
38520 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69  e is no.** expli
38530 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 5b  citly declared [
38540 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
38550 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65  KEY] column, the
38560 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20  n the output.** 
38570 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73  parameters are s
38580 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  et as follows:.*
38590 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20  *.** <pre>.**   
385a0 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e    data type: "IN
385b0 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f  TEGER".**     co
385c0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
385d0 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20  : "BINARY".**   
385e0 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a    not null: 0.**
385f0 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79       primary key
38600 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20  : 1.**     auto 
38610 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20  increment: 0.** 
38620 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  </pre>)^.**.** ^
38630 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d  (This function m
38640 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d  ay load one or m
38650 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d  ore schemas from
38660 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e   database files.
38670 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20   If an.** error 
38680 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
38690 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  is process, or i
386a0 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  f the requested 
386b0 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a  table or column.
386c0 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75  ** cannot be fou
386d0 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  nd, an [error co
386e0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  de] is returned 
386f0 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  and an error mes
38700 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20  sage left.** in 
38710 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
38720 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65  nnection] (to be
38730 20 72 65 74 72 69 65 76 65 64 20 75 73 69 6e 67   retrieved using
38740 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
38750 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  )).)^.**.** ^Thi
38760 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76  s API is only av
38770 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
38780 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
38790 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
387a0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
387b0 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
387c0 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
387d0 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a  ymbol defined..*
387e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61  /.int sqlite3_ta
387f0 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64  ble_column_metad
38800 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ata(.  sqlite3 *
38810 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
38820 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e