/ Hex Artifact Content
Login

Artifact e7a96fad3f5a2e96f5b69cf395d3dfa657f4ab59:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e  ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2f20: 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61  ) is called on a
2f30: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f40: 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c  ction] that stil
2f50: 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e  l has.** outstan
2f60: 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73  ding [prepared s
2f70: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f  tatements], [BLO
2f80: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f  B handles], and/
2f90: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  or.** [sqlite3_b
2fa0: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74  ackup] objects t
2fb0: 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53  hen it returns S
2fc0: 51 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65  QLITE_OK but the
2fd0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
2fe0: 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73   of resources is
2ff0: 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
3000: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
3010: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42  atements], [BLOB
3020: 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e   handles],.** an
3030: 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  d [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61  p] objects are a
3050: 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  lso destroyed..*
3060: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c  *.** ^If an [sql
3070: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
3080: 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20  destroyed while 
3090: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
30a0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
30b0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
30c0: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
30d0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
30e0: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
30f0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
3100: 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  C)] and [sqlite3
3110: 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a  _close_v2(C)].**
3120: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
3130: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
3140: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
3150: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
3160: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3170: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
3180: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
3190: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
31a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
31b0: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69  ], and not previ
31c0: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a  ously closed..**
31d0: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
31e0: 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c  3_close() or sql
31f0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
3200: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
3210: 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ter.** argument 
3220: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
3230: 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  -op..*/.int sqli
3240: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
3250: 33 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  3*);.int sqlite3
3260: 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65  _close_v2(sqlite
3270: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  3*);../*.** The 
3280: 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62  type for a callb
3290: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ack function..**
32a0: 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20   This is legacy 
32b0: 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20  and deprecated. 
32c0: 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20   It is included 
32d0: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a  for historical.*
32e0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
32f0: 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d  and is not docum
3300: 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65  ented..*/.typede
3310: 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f  f int (*sqlite3_
3320: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3330: 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72  int,char**, char
3340: 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  **);../*.** CAPI
3350: 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51  3REF: One-Step Q
3360: 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49  uery Execution I
3370: 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54  nterface.**.** T
3380: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3390: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61  ) interface is a
33a0: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61   convenience wra
33b0: 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
33c0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
33d0: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
33e0: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
33f0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
3400: 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77  ],.** that allow
3410: 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
3420: 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65   to run multiple
3430: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53   statements of S
3440: 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61  QL.** without ha
3450: 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f  ving to use a lo
3460: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a  t of C code. .**
3470: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
3480: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
3490: 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d  e runs zero or m
34a0: 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ore UTF-8 encode
34b0: 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  d,.** semicolon-
34c0: 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61  separate SQL sta
34d0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
34e0: 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75  nto its 2nd argu
34f0: 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20  ment,.** in the 
3500: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b  context of the [
3510: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3520: 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61  ion] passed in a
3530: 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67  s its 1st.** arg
3540: 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ument.  ^If the 
3550: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3560: 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67  n of the 3rd arg
3570: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
3580: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
3590: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20  t NULL, then it 
35a0: 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65  is invoked for e
35b0: 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a  ach result row.*
35c0: 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20  * coming out of 
35d0: 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51  the evaluated SQ
35e0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e  L statements.  ^
35f0: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
3600: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   to.** sqlite3_e
3610: 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64  xec() is relayed
3620: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
3630: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  1st argument of 
3640: 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  each.** callback
3650: 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49   invocation.  ^I
3660: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70  f the callback p
3670: 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
3680: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e  3_exec().** is N
3690: 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c  ULL, then no cal
36a0: 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e  lback is ever in
36b0: 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74  voked and result
36c0: 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e   rows are.** ign
36d0: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ored..**.** ^If 
36e0: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
36f0: 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
3700: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3710: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  nts passed into.
3720: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3730: 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f  ), then executio
3740: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
3750: 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73   statement stops
3760: 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65   and.** subseque
3770: 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  nt statements ar
3780: 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20  e skipped.  ^If 
3790: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
37a0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
37b0: 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  c().** is not NU
37c0: 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f  LL then any erro
37d0: 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69  r message is wri
37e0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
37f0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3800: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
3810: 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20  c()] and passed 
3820: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
3830: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a   5th parameter..
3840: 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f  ** To avoid memo
3850: 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70  ry leaks, the ap
3860: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
3870: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
3880: 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65  _free()].** on e
3890: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
38a0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68  ings returned th
38b0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
38c0: 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66  rameter of.** of
38d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38e0: 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20  after the error 
38f0: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
3900: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  s no longer need
3910: 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35  ed..** ^If the 5
3920: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3940: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e  s not NULL and n
3950: 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75  o errors.** occu
3960: 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
3970: 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20  exec() sets the 
3980: 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35  pointer in its 5
3990: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
39a0: 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72  ** NULL before r
39b0: 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
39c0: 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65  ^If an sqlite3_e
39d0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72  xec() callback r
39e0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
39f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3a00: 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  c().** routine r
3a10: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42  eturns SQLITE_AB
3a20: 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f  ORT without invo
3a30: 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63  king the callbac
3a40: 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77  k again and.** w
3a50: 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61  ithout running a
3a60: 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51  ny subsequent SQ
3a70: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
3a80: 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67  .** ^The 2nd arg
3a90: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3aa0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3ab0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73  back function is
3ac0: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
3ad0: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
3ae0: 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33   result.  ^The 3
3af0: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rd argument to t
3b00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3b10: 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73  ).** callback is
3b20: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3b30: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3b40: 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20   obtained as if 
3b50: 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
3b60: 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
3b70: 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f   one for each co
3b80: 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c  lumn.  ^If an el
3b90: 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65  ement of a.** re
3ba0: 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c  sult row is NULL
3bb0: 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   then the corres
3bc0: 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70  ponding string p
3bd0: 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a  ointer for the.*
3be0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
3bf0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e   callback is a N
3c00: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
3c10: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
3c20: 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  to the.** sqlite
3c30: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3c40: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3c50: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3c60: 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a  ings where each.
3c70: 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65  ** entry represe
3c80: 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  nts the name of 
3c90: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65  corresponding re
3ca0: 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f  sult column as o
3cb0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3cc0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
3cd0: 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  name()]..**.** ^
3ce0: 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
3cf0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3d00: 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c  exec() is a NULL
3d10: 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e   pointer, a poin
3d20: 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70  ter.** to an emp
3d30: 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20  ty string, or a 
3d40: 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e  pointer that con
3d50: 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65  tains only white
3d60: 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a  space and/or .**
3d70: 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74   SQL comments, t
3d80: 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65  hen no SQL state
3d90: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61  ments are evalua
3da0: 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61  ted and the data
3db0: 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  base.** is not c
3dc0: 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  hanged..**.** Re
3dd0: 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a  strictions:.**.*
3de0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
3df0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e00: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
3e10: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
3e20: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3e30: 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61  c().**      is a
3e40: 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20   valid and open 
3e50: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3e60: 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  tion]..** <li> T
3e70: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e80: 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
3e90: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
3ea0: 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
3eb0: 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65  d by.**      the
3ec0: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3ed0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3ee0: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3ef0: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3f00: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
3f10: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
3f20: 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51  ot modify the SQ
3f30: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
3f40: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3f50: 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72       the 2nd par
3f60: 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
3f70: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3f80: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3f90: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75   running..** </u
3fa0: 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
3fb0: 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65  3_exec(.  sqlite
3fc0: 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  3*,             
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
3ff0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
4000: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20  nst char *sql,  
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20           /* SQL 
4030: 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
4040: 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62  */.  int (*callb
4050: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
4060: 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20  har**,char**),  
4070: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63  /* Callback func
4080: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
4090: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75       /* 1st argu
40c0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b  ment to callback
40d0: 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72   */.  char **err
40e0: 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20  msg             
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4100: 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
4110: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
4120: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
4130: 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  : Result Codes.*
4140: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
4150: 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64  TE_OK {error cod
4160: 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d  e} {error codes}
4170: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72  .** KEYWORDS: {r
4180: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73  esult code} {res
4190: 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a  ult codes}.**.**
41a0: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
41b0: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
41c0: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
41d0: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
41e0: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
41f0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
4200: 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20  cate success or 
4210: 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e  failure..**.** N
4220: 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d  ew error codes m
4230: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
4240: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
4250: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
4260: 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
4270: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
4280: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4290: 6f 64 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  odes],.** [sqlit
42a0: 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
42b0: 69 63 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f 52  ict()] [SQLITE_R
42c0: 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c 74  OLLBACK | result
42d0: 20 63 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66   codes]..*/.#def
42e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20  ine SQLITE_OK   
42f0: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53          0   /* S
4300: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74  uccessful result
4310: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67   */./* beginning
4320: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4330: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4340: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31  E_ERROR        1
4350: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20     /* SQL error 
4360: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62  or missing datab
4370: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
4380: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20  QLITE_INTERNAL  
4390: 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e     2   /* Intern
43a0: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69  al logic error i
43b0: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66  n SQLite */.#def
43c0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20  ine SQLITE_PERM 
43d0: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41          3   /* A
43e0: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e  ccess permission
43f0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
4400: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ne SQLITE_ABORT 
4410: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61         4   /* Ca
4420: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
4430: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72  equested an abor
4440: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4450: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20  ITE_BUSY        
4460: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61   5   /* The data
4470: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63  base file is loc
4480: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
4490: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20  QLITE_LOCKED    
44a0: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c     6   /* A tabl
44b0: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  e in the databas
44c0: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
44d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
44e0: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f  MEM        7   /
44f0: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69  * A malloc() fai
4500: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  led */.#define S
4510: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20  QLITE_READONLY  
4520: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70     8   /* Attemp
4530: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61  t to write a rea
4540: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a  donly database *
4550: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4560: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20  _INTERRUPT    9 
4570: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74    /* Operation t
4580: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c  erminated by sql
4590: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
45a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
45b0: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30  E_IOERR       10
45c0: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20     /* Some kind 
45d0: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f  of disk I/O erro
45e0: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64  r occurred */.#d
45f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
4600: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a  RUPT     11   /*
4610: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69   The database di
4620: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66  sk image is malf
4630: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ormed */.#define
4640: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
4650: 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e      12   /* Unkn
4660: 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71  own opcode in sq
4670: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
4680: 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ol() */.#define 
4690: 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20  SQLITE_FULL     
46a0: 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72     13   /* Inser
46b0: 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61  tion failed beca
46c0: 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20  use database is 
46d0: 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  full */.#define 
46e0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
46f0: 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c     14   /* Unabl
4700: 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
4710: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
4720: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
4730: 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f  OTOCOL    15   /
4740: 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20  * Database lock 
4750: 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a  protocol error *
4760: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4770: 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20  _EMPTY       16 
4780: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73    /* Database is
4790: 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e   empty */.#defin
47a0: 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20  e SQLITE_SCHEMA 
47b0: 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65       17   /* The
47c0: 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
47d0: 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66   changed */.#def
47e0: 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49  ine SQLITE_TOOBI
47f0: 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53  G      18   /* S
4800: 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78  tring or BLOB ex
4810: 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74  ceeds size limit
4820: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4830: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31  TE_CONSTRAINT  1
4840: 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65  9   /* Abort due
4850: 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76   to constraint v
4860: 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66  iolation */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41  ine SQLITE_MISMA
4880: 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44  TCH    20   /* D
4890: 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63  ata type mismatc
48a0: 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  h */.#define SQL
48b0: 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20  ITE_MISUSE      
48c0: 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20  21   /* Library 
48d0: 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  used incorrectly
48e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
48f0: 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32  TE_NOLFS       2
4900: 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66  2   /* Uses OS f
4910: 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70  eatures not supp
4920: 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f  orted on host */
4930: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4940: 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20  AUTH        23  
4950: 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f   /* Authorizatio
4960: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
4970: 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41  ine SQLITE_FORMA
4980: 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41  T      24   /* A
4990: 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73  uxiliary databas
49a0: 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a  e format error *
49b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
49c0: 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20  _RANGE       25 
49d0: 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74    /* 2nd paramet
49e0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
49f0: 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  nd out of range 
4a00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4a10: 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36  E_NOTADB      26
4a20: 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65     /* File opene
4a30: 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20  d that is not a 
4a40: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
4a50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4a60: 4e 4f 54 49 43 45 20 20 20 20 20 20 32 37 20 20  NOTICE      27  
4a70: 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e   /* Notification
4a80: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c  s from sqlite3_l
4a90: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  og() */.#define 
4aa0: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20  SQLITE_WARNING  
4ab0: 20 20 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69     28   /* Warni
4ac0: 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ngs from sqlite3
4ad0: 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e  _log() */.#defin
4ae0: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4af0: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4b00: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4b10: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4b20: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4b30: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4b40: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4b50: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4b60: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4b70: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4b80: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4b90: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4ba0: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4bb0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4bc0: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
4bd0: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4be0: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4bf0: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4c00: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4c10: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4c20: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4c30: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4c40: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4c50: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4c60: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4c70: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
4c80: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
4c90: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
4ca0: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
4cb0: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
4cc0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
4cd0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4ce0: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4cf0: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4d00: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4d10: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4d20: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4d30: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4d40: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4d50: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4d60: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4d70: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4d80: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
4d90: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
4da0: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
4db0: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
4dc0: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
4dd0: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4de0: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4df0: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4e00: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4e10: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4e20: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4e30: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4e40: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4e50: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4e60: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4e70: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
4e80: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
4e90: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
4ea0: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
4eb0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4ec0: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
4ed0: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4ee0: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
4ef0: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
4f00: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 69 6e 63  t codes will inc
4f10: 72 65 61 73 65 0a 2a 2a 20 6f 76 65 72 20 74 69  rease.** over ti
4f20: 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  me.  Software th
4f30: 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64  at uses extended
4f40: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68   result codes sh
4f50: 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74  ould expect.** t
4f60: 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74  o see new result
4f70: 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65   codes in future
4f80: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
4f90: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  ite..**.** The S
4fa0: 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20  QLITE_OK result 
4fb0: 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  code will never 
4fc0: 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74  be extended.  It
4fd0: 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20   will always.** 
4fe0: 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e  be exactly zero.
4ff0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5000: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20  TE_IOERR_READ   
5010: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5020: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38  TE_IOERR | (1<<8
5030: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5040: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
5050: 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  AD        (SQLIT
5060: 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29  E_IOERR | (2<<8)
5070: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5080: 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20  _IOERR_WRITE    
5090: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50a0: 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29  _IOERR | (3<<8))
50b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50c0: 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20  IOERR_FSYNC     
50d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
50e0: 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a  IOERR | (4<<8)).
50f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5100: 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20  OERR_DIR_FSYNC  
5110: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5120: 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23  OERR | (5<<8)).#
5130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5140: 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20  ERR_TRUNCATE    
5150: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5160: 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  ERR | (6<<8)).#d
5170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5180: 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20  RR_FSTAT        
5190: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
51a0: 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  RR | (7<<8)).#de
51b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
51c0: 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_UNLOCK        
51d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
51e0: 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  R | (8<<8)).#def
51f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5200: 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _RDLOCK         
5210: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5220: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5240: 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
5250: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5260: 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (10<<8)).#defi
5270: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5280: 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20  BLOCKED         
5290: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
52a0: 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (11<<8)).#defi
52b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
52c0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20  NOMEM           
52d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
52e0: 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (12<<8)).#defi
52f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5300: 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20  ACCESS          
5310: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5320: 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (13<<8)).#defi
5330: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5340: 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43  CHECKRESERVEDLOC
5350: 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  K (SQLITE_IOERR 
5360: 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (14<<8)).#defi
5370: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5380: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5390: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
53a0: 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (15<<8)).#defi
53b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
53c0: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20  CLOSE           
53d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
53e0: 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (16<<8)).#defi
53f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5400: 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  DIR_CLOSE       
5410: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5420: 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (17<<8)).#defi
5430: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5440: 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20  SHMOPEN         
5450: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5460: 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (18<<8)).#defi
5470: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5480: 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20  SHMSIZE         
5490: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54a0: 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69  | (19<<8)).#defi
54b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
54c0: 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  SHMLOCK         
54d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54e0: 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (20<<8)).#defi
54f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5500: 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20  SHMMAP          
5510: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5520: 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (21<<8)).#defi
5530: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5540: 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20  SEEK            
5550: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5560: 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (22<<8)).#defi
5570: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5580: 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20  DELETE_NOENT    
5590: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55a0: 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (23<<8)).#defi
55b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
55c0: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
55d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55e0: 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (24<<8)).#defi
55f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5600: 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 20  GETTEMPPATH     
5610: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5620: 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (25<<8)).#defi
5630: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5640: 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 20  CONVPATH        
5650: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5660: 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (26<<8)).#defi
5670: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
5680: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
5690: 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44    (SQLITE_LOCKED
56a0: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66   |  (1<<8)).#def
56b0: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f  ine SQLITE_BUSY_
56c0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 20  RECOVERY        
56d0: 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20     (SQLITE_BUSY 
56e0: 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65    |  (1<<8)).#de
56f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5700: 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20  _SNAPSHOT       
5710: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5720: 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64     |  (2<<8)).#d
5730: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5740: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
5750: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5760: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
5770: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5780: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
5790: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
57a0: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
57b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
57c0: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
57d0: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
57e0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
57f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5800: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56  TE_CANTOPEN_CONV
5810: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5820: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34  TE_CANTOPEN | (4
5830: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5840: 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41  LITE_CORRUPT_VTA
5850: 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  B            (SQ
5860: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28  LITE_CORRUPT | (
5870: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5880: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52  QLITE_READONLY_R
5890: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53  ECOVERY       (S
58a0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
58b0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
58c0: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
58d0: 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20  _CANTLOCK       
58e0: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
58f0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5900: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5910: 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20  LY_ROLLBACK     
5920: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5930: 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  LY | (3<<8)).#de
5940: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52  fine SQLITE_ABOR
5950: 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20  T_ROLLBACK      
5960: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52      (SQLITE_ABOR
5970: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  T | (2<<8)).#def
5980: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5990: 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20  RAINT_CHECK     
59a0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
59b0: 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a  RAINT | (1<<8)).
59c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
59d0: 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54  ONSTRAINT_COMMIT
59e0: 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43  HOOK   (SQLITE_C
59f0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c  ONSTRAINT | (2<<
5a00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5a10: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f  TE_CONSTRAINT_FO
5a20: 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49  REIGNKEY   (SQLI
5a30: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5a40: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
5a50: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5a60: 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28  T_FUNCTION     (
5a70: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5a80: 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  T | (4<<8)).#def
5a90: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5aa0: 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20  RAINT_NOTNULL   
5ab0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5ac0: 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a  RAINT | (5<<8)).
5ad0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5ae0: 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52  ONSTRAINT_PRIMAR
5af0: 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43  YKEY   (SQLITE_C
5b00: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c  ONSTRAINT | (6<<
5b10: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5b20: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52  TE_CONSTRAINT_TR
5b30: 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c 49  IGGER      (SQLI
5b40: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5b50: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
5b60: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b70: 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 28  T_UNIQUE       (
5b80: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b90: 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  T | (8<<8)).#def
5ba0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5bb0: 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20  RAINT_VTAB      
5bc0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5bd0: 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a  RAINT | (9<<8)).
5be0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5bf0: 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 20  ONSTRAINT_ROWID 
5c00: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5c10: 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c  ONSTRAINT |(10<<
5c20: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5c30: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45  TE_NOTICE_RECOVE
5c40: 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c 49  R_WAL      (SQLI
5c50: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c  TE_NOTICE | (1<<
5c60: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5c70: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45  TE_NOTICE_RECOVE
5c80: 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49  R_ROLLBACK (SQLI
5c90: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c  TE_NOTICE | (2<<
5ca0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5cb0: 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49  TE_WARNING_AUTOI
5cc0: 4e 44 45 58 20 20 20 20 20 20 20 28 53 51 4c 49  NDEX       (SQLI
5cd0: 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c  TE_WARNING | (1<
5ce0: 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  <8))../*.** CAPI
5cf0: 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20  3REF: Flags For 
5d00: 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74  File Open Operat
5d10: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
5d20: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20   bit values are 
5d30: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
5d40: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70   in the.** 3rd p
5d50: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
5d60: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
5d70: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
5d80: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20  d.** in the 4th 
5d90: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5da0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
5db0: 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a  pen] method..*/.
5dc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5dd0: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  PEN_READONLY    
5de0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20       0x00000001 
5df0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5e00: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5e10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5e20: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20  PEN_READWRITE   
5e30: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20       0x00000002 
5e40: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5e50: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5e60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5e70: 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20  PEN_CREATE      
5e80: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20       0x00000004 
5e90: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5ea0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5eb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5ec0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
5ed0: 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20  E    0x00000008 
5ee0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5ef0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5f00: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20  PEN_EXCLUSIVE   
5f10: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20       0x00000010 
5f20: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5f30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5f40: 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20  PEN_AUTOPROXY   
5f50: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20       0x00000020 
5f60: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5f70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5f80: 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20  PEN_URI         
5f90: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20       0x00000040 
5fa0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5fb0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5fc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5fd0: 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20  PEN_MEMORY      
5fe0: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 20       0x00000080 
5ff0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6000: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6010: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6020: 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20  PEN_MAIN_DB     
6030: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20       0x00000100 
6040: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6050: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6060: 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20  PEN_TEMP_DB     
6070: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20       0x00000200 
6080: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6090: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
60a0: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
60b0: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20       0x00000400 
60c0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
60d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
60e0: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
60f0: 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20       0x00000800 
6100: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6110: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6120: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
6130: 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20       0x00001000 
6140: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6160: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20  PEN_SUBJOURNAL  
6170: 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20       0x00002000 
6180: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6190: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
61a0: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
61b0: 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20  AL   0x00004000 
61c0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
61d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
61e0: 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20  PEN_NOMUTEX     
61f0: 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20       0x00008000 
6200: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6210: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6220: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6230: 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20  PEN_FULLMUTEX   
6240: 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20       0x00010000 
6250: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6260: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6270: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6280: 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
6290: 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20       0x00020000 
62a0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
62b0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
62c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
62d0: 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
62e0: 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20       0x00040000 
62f0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6300: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6310: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6320: 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20  PEN_WAL         
6330: 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20       0x00080000 
6340: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6350: 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20  ./* Reserved:   
6360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6370: 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30        0x00F00000
6380: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
6390: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
63a0: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
63b0: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61  * The xDeviceCha
63c0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
63d0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
63e0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
63f0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
6400: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
6410: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
6420: 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76  f these.** bit v
6430: 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67  alues expressing
6440: 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73   I/O characteris
6450: 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73  tics of the mass
6460: 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69   storage.** devi
6470: 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68  ce that holds th
6480: 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20  e file that the 
6490: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
64a0: 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74  ods].** refers t
64b0: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  o..**.** The SQL
64c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
64d0: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
64e0: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
64f0: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
6500: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6510: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6520: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
6530: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
6540: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
6550: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
6560: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
6570: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
6580: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
6590: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
65a0: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
65b0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
65c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
65d0: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
65e0: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
65f0: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
6600: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
6610: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
6620: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
6630: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
6640: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
6650: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
6660: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
6670: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6680: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
6690: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
66a0: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
66b0: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
66c0: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
66d0: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
66e0: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20  ** to xWrite(). 
66f0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6700: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
6710: 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d  WRITE property m
6720: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74  eans that.** aft
6730: 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77  er reboot follow
6740: 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70  ing a crash or p
6750: 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f  ower loss, the o
6760: 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a  nly bytes in a.*
6770: 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65  * file that were
6780: 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20   written at the 
6790: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65  application leve
67a0: 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61  l might have cha
67b0: 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74  nged.** and that
67c0: 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c   adjacent bytes,
67d0: 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68   even bytes with
67e0: 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74  in the same sect
67f0: 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e  or are.** guaran
6800: 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61  teed to be uncha
6810: 6e 67 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  nged..*/.#define
6820: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6830: 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20  OMIC            
6840: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a       0x00000001.
6850: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6860: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20  OCAP_ATOMIC512  
6870: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6880: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
6890: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
68a0: 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC1K            
68b0: 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64     0x00000004.#d
68c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
68d0: 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20  AP_ATOMIC2K     
68e0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
68f0: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c  0008.#define SQL
6900: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6910: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6920: 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66   0x00000010.#def
6930: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6940: 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20  _ATOMIC8K       
6950: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6960: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
6970: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
6980: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6990: 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e  x00000040.#defin
69a0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
69b0: 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20  TOMIC32K        
69c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
69d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
69e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20  IOCAP_ATOMIC64K 
69f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6a00: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20  0000100.#define 
6a10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
6a20: 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20  E_APPEND        
6a30: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23      0x00000200.#
6a40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6a50: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20  CAP_SEQUENTIAL  
6a60: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6a70: 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00400.#define SQ
6a80: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
6a90: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
6aa0: 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65    0x00000800.#de
6ab0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6ac0: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
6ad0: 57 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31  WRITE    0x00001
6ae0: 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  000../*.** CAPI3
6af0: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
6b00: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53  g Levels.**.** S
6b10: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
6b20: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
6b30: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
6b40: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
6b50: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
6b60: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
6b70: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
6b80: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
6b90: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6ba0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
6bb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6bc0: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
6bd0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
6be0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
6bf0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
6c00: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
6c10: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
6c20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6c30: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
6c40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6c50: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
6c60: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
6c70: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
6c80: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
6c90: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
6ca0: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
6cb0: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
6cc0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
6cd0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6ce0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
6cf0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
6d00: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
6d10: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
6d20: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
6d30: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
6d40: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
6d50: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
6d60: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
6d70: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
6d80: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
6d90: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
6da0: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
6db0: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
6dc0: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
6dd0: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
6de0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
6df0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
6e00: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
6e10: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
6e20: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
6e30: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
6e40: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
6e50: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
6e60: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
6e70: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
6e80: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
6e90: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
6ea0: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
6eb0: 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e  nc()..**.** Do n
6ec0: 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53  ot confuse the S
6ed0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6ee0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
6ef0: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20  C_FULL flags.** 
6f00: 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41  with the [PRAGMA
6f10: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f   synchronous]=NO
6f20: 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41  RMAL and [PRAGMA
6f30: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55   synchronous]=FU
6f40: 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20  LL.** settings. 
6f50: 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75   The [synchronou
6f60: 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d  s pragma] determ
6f70: 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20  ines when calls 
6f80: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20  to the.** xSync 
6f90: 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72  VFS method occur
6fa0: 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69   and applies uni
6fb0: 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c  formly across al
6fc0: 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20  l platforms..** 
6fd0: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
6fe0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
6ff0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
7000: 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a  s determine how.
7010: 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20  ** energetic or 
7020: 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63  rigorous or forc
7030: 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70  eful the sync op
7040: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64  erations are and
7050: 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20  .** only make a 
7060: 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61  difference on Ma
7070: 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65  c OSX for the de
7080: 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64  fault SQLite cod
7090: 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72  e..** (Third-par
70a0: 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ty VFS implement
70b0: 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73  ations might als
70c0: 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  o make the disti
70d0: 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
70e0: 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  n SQLITE_SYNC_NO
70f0: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
7100: 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61  SYNC_FULL, but a
7110: 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72  mong the.** oper
7120: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61  ating systems na
7130: 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64  tively supported
7140: 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79   by SQLite, only
7150: 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65   Mac OSX.** care
7160: 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66  s about the diff
7170: 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66  erence.).*/.#def
7180: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
7190: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
71a0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
71b0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
71c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
71d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
71e0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
71f0: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a    0x00010../*.**
7200: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7210: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c  terface Open Fil
7220: 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41  e Handle.**.** A
7230: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
7240: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
7250: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ts an open file 
7260: 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  in the .** [sqli
7270: 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74  te3_vfs | OS int
7280: 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20  erface layer].  
7290: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
72a0: 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65  terface.** imple
72b0: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
72c0: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
72d0: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
72e0: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
72f0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
7300: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
7310: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
7320: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
7330: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
7340: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7350: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
7360: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
7370: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
7380: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
7390: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
73a0: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
73b0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
73c0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
73d0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
73e0: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
73f0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
7400: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
7410: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
7420: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
7430: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
7440: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
7450: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
7460: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a   Methods Object.
7470: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
7480: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
7490: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
74a0: 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61  n] method popula
74b0: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74  tes an.** [sqlit
74c0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
74d0: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e  (or, more common
74e0: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ly, a subclass o
74f0: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
7500: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20  3_file] object) 
7510: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74  with a pointer t
7520: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
7530: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a   this object..**
7540: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
7550: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73  ines the methods
7560: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d   used to perform
7570: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69   various operati
7580: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74  ons.** against t
7590: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70  he open file rep
75a0: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20  resented by the 
75b0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
75c0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  bject..**.** If 
75d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
75e0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73  .xOpen] method s
75f0: 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ets the sqlite3_
7600: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
7610: 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e  ement .** to a n
7620: 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
7630: 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
7640: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c  3_io_methods.xCl
7650: 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61  ose method.** ma
7660: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65  y be invoked eve
7670: 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n if the [sqlite
7680: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70  3_vfs.xOpen] rep
7690: 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61  orted that it fa
76a0: 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e  iled.  The.** on
76b0: 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e  ly way to preven
76c0: 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f  t a call to xClo
76d0: 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  se following a f
76e0: 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76  ailed [sqlite3_v
76f0: 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20  fs.xOpen].** is 
7700: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
7710: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73  _vfs.xOpen] to s
7720: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
7730: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
7740: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e  ment.** to NULL.
7750: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
7760: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79   argument to xSy
7770: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nc may be one of
7780: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f   [SQLITE_SYNC_NO
7790: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  RMAL] or.** [SQL
77a0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20  ITE_SYNC_FULL]. 
77b0: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63   The first choic
77c0: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20  e is the normal 
77d0: 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20  fsync()..** The 
77e0: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73  second choice is
77f0: 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c   a Mac OS X styl
7800: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65  e fullsync.  The
7810: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41   [SQLITE_SYNC_DA
7820: 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20  TAONLY].** flag 
7830: 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74  may be ORed in t
7840: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
7850: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66  only the data of
7860: 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64   the file.** and
7870: 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e   not its inode n
7880: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65  eeds to be synce
7890: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  d..**.** The int
78a0: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
78b0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
78c0: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
78d0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
78e0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
78f0: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
7900: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
7910: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
7920: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
7930: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
7940: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
7950: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
7960: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
7970: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  VE]..** </ul>.**
7980: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73   xLock() increas
7990: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e  es the lock. xUn
79a0: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73  lock() decreases
79b0: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68   the lock..** Th
79c0: 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  e xCheckReserved
79d0: 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68  Lock() method ch
79e0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79  ecks whether any
79f0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
7a00: 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20  tion,.** either 
7a10: 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  in this process 
7a20: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72  or in some other
7a30: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c   process, is hol
7a40: 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c  ding a RESERVED,
7a50: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
7a60: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
7a70: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
7a80: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
7a90: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
7aa0: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
7ab0: 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
7ac0: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   The xFileContro
7ad0: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20  l() method is a 
7ae0: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63  generic interfac
7af0: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75  e that allows cu
7b00: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c  stom.** VFS impl
7b10: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64  ementations to d
7b20: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20  irectly control 
7b30: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69  an open file usi
7b40: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
7b50: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
7b60: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  )] interface.  T
7b70: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61  he second "op" a
7b80: 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a  rgument is an.**
7b90: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e   integer opcode.
7ba0: 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
7bb0: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69  ment is a generi
7bc0: 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64  c pointer intend
7bd0: 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74  ed to.** point t
7be0: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
7bf0: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61  at may contain a
7c00: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63  rguments or spac
7c10: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a  e in which to.**
7c20: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61   write return va
7c30: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c  lues.  Potential
7c40: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43   uses for xFileC
7c50: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62  ontrol() might b
7c60: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74  e.** functions t
7c70: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e  o enable blockin
7c80: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d  g locks with tim
7c90: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65  eouts, to change
7ca0: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20   the.** locking 
7cb0: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78  strategy (for ex
7cc0: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74  ample to use dot
7cd0: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f  -file locks), to
7ce0: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75   inquire.** abou
7cf0: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
7d00: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72  a lock, or to br
7d10: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e  eak stale locks.
7d20: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20    The SQLite.** 
7d30: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c  core reserves al
7d40: 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74  l opcodes less t
7d50: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20  han 100 for its 
7d60: 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53  own use..** A [S
7d70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
7d80: 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20  STATE | list of 
7d90: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68  opcodes] less th
7da0: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61  an 100 is availa
7db0: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ble..** Applicat
7dc0: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65  ions that define
7dd0: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43   a custom xFileC
7de0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68  ontrol method sh
7df0: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73  ould use opcodes
7e00: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
7e10: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
7e20: 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d  nflicts.  VFS im
7e30: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
7e40: 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
7e50: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
7e60: 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f   for file contro
7e70: 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74  l opcodes that t
7e80: 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65  hey do not.** re
7e90: 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54  cognize..**.** T
7ea0: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
7eb0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
7ec0: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
7ed0: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
7ee0: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
7ef0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
7f00: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
7f10: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
7f20: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
7f30: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
7f40: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
7f50: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
7f60: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
7f70: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
7f80: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
7f90: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
7fa0: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
7fb0: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
7fc0: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
7fd0: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
7fe0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
7ff0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
8000: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8010: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
8020: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8030: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
8040: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8050: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
8060: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8070: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
8080: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8090: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
80a0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
80b0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
80c0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
80d0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
80e0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
80f0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
8100: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
8110: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
8120: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
8130: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
8140: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  UENTIAL].** </ul
8150: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
8160: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
8170: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8180: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
8190: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
81a0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
81b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
81c0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
81d0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
81e0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
81f0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
8200: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
8210: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
8220: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
8230: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
8240: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
8250: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8260: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8270: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
8280: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
8290: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
82a0: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
82b0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
82c0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
82d0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
82e0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
82f0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
8300: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
8310: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8320: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
8330: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
8340: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
8350: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
8360: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
8370: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
8380: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
8390: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
83a0: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
83b0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
83c0: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
83d0: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
83e0: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
83f0: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
8400: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
8410: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
8420: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
8430: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
8440: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
8450: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
8460: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
8470: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
8480: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
8490: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
84a0: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
84b0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
84c0: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
84d0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
84e0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
84f0: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
8500: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
8510: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
8520: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8530: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
8540: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
8550: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
8560: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
8570: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
8580: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
8590: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
85a0: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
85b0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
85c0: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
85d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
85e0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
85f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
8600: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8610: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
8620: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
8630: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8640: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
8650: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
8660: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8670: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
8680: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
8690: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
86a0: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
86b0: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
86c0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
86d0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
86e0: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
86f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8700: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
8710: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
8720: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
8730: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8740: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
8750: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
8760: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65  _file*);.  /* Me
8770: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8780: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8790: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 1 */.  int (*x
87a0: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f  ShmMap)(sqlite3_
87b0: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20  file*, int iPg, 
87c0: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76  int pgsz, int, v
87d0: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b  oid volatile**);
87e0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63  .  int (*xShmLoc
87f0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8800: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e  , int offset, in
8810: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  t n, int flags);
8820: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61  .  void (*xShmBa
8830: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66  rrier)(sqlite3_f
8840: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
8850: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65  ShmUnmap)(sqlite
8860: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c  3_file*, int del
8870: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d  eteFlag);.  /* M
8880: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8890: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
88a0: 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 2 */.  int (*
88b0: 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  xFetch)(sqlite3_
88c0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
88d0: 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20  nt64 iOfst, int 
88e0: 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29  iAmt, void **pp)
88f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74  ;.  int (*xUnfet
8900: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
8910: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8920: 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29   iOfst, void *p)
8930: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8940: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8950: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a  or version 3 */.
8960: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20    /* Additional 
8970: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61  methods may be a
8980: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
8990: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f  eleases */.};../
89a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
89b0: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e  tandard File Con
89c0: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a  trol Opcodes.**.
89d0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
89e0: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f   constants are o
89f0: 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78  pcodes for the x
8a00: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
8a10: 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  od.** of the [sq
8a20: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8a30: 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72  ] object and for
8a40: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
8a50: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a  le_control()].**
8a60: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
8a70: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
8a80: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f  NTL_LOCKSTATE] o
8a90: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
8aa0: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
8ab0: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
8ac0: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
8ad0: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77  trol method to w
8ae0: 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74  rite the current
8af0: 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65   state of.** the
8b00: 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53   lock (one of [S
8b10: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d  QLITE_LOCK_NONE]
8b20: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  , [SQLITE_LOCK_S
8b30: 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  HARED],.** [SQLI
8b40: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
8b50: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
8b60: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51  PENDING], or [SQ
8b70: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
8b80: 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e  IVE]).** into an
8b90: 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68   integer that th
8ba0: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20  e pArg argument 
8bb0: 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20  points to. This 
8bc0: 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
8bd0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
8be0: 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  ting and only ne
8bf0: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
8c00: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
8c10: 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e  TEST.** is defin
8c20: 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  ed..** <ul>.** <
8c30: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8c40: 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a  L_SIZE_HINT]].**
8c50: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8c60: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70  TL_SIZE_HINT] op
8c70: 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79 20  code is used by 
8c80: 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74  SQLite to give t
8c90: 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20  he VFS.** layer 
8ca0: 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61  a hint of how la
8cb0: 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  rge the database
8cc0: 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20   file will grow 
8cd0: 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68 65  to be during the
8ce0: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e  .** current tran
8cf0: 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68  saction.  This h
8d00: 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61  int is not guara
8d10: 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63 75  nteed to be accu
8d20: 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69  rate but it.** i
8d30: 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20  s often close.  
8d40: 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56  The underlying V
8d50: 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20  FS might choose 
8d60: 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64  to preallocate d
8d70: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
8d80: 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74  space based on t
8d90: 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65  his hint in orde
8da0: 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73  r to help writes
8db0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
8dc0: 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73  .** file run fas
8dd0: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ter..**.** <li>[
8de0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
8df0: 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68  UNK_SIZE]].** Th
8e00: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8e10: 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f  CHUNK_SIZE] opco
8e20: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  de is used to re
8e30: 71 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56  quest that the V
8e40: 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e  FS.** extends an
8e50: 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20  d truncates the 
8e60: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e  database file in
8e70: 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a   chunks of a siz
8e80: 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
8e90: 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20  y the user. The 
8ea0: 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
8eb0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  to [sqlite3_file
8ec0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75  _control()] shou
8ed0: 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20  ld .** point to 
8ee0: 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65  an integer (type
8ef0: 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67   int) containing
8f00: 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73   the new chunk-s
8f10: 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f  ize to use.** fo
8f20: 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20  r the nominated 
8f30: 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61  database. Alloca
8f40: 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69  ting database fi
8f50: 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67  le space in larg
8f60: 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79  e.** chunks (say
8f70: 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c   1MB at a time),
8f80: 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65   may reduce file
8f90: 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74  -system fragment
8fa0: 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70  ation and.** imp
8fb0: 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  rove performance
8fc0: 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73   on some systems
8fd0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
8fe0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
8ff0: 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65  POINTER]].** The
9000: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46   [SQLITE_FCNTL_F
9010: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63  ILE_POINTER] opc
9020: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f  ode is used to o
9030: 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a  btain a pointer.
9040: 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
9050: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
9060: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
9070: 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74  a particular dat
9080: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
9090: 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73  ion.  See the [s
90a0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
90b0: 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61  rol()] documenta
90c0: 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69  tion for.** addi
90d0: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
90e0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  on..**.** <li>[[
90f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9100: 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e  C_OMITTED]].** ^
9110: 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  (The [SQLITE_FCN
9120: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d  TL_SYNC_OMITTED]
9130: 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72   opcode is gener
9140: 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ated internally 
9150: 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64  by.** SQLite and
9160: 20 73 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53   sent to all VFS
9170: 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 61  es in place of a
9180: 20 63 61 6c 6c 20 74 6f 20 74 68 65 20 78 53 79   call to the xSy
9190: 6e 63 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65  nc method.** whe
91a0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
91b0: 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b 50  onnection has [P
91c0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
91d0: 73 5d 20 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e  s] set to OFF.)^
91e0: 0a 2a 2a 20 53 6f 6d 65 20 73 70 65 63 69 61 6c  .** Some special
91f0: 69 7a 65 64 20 56 46 53 65 73 20 6e 65 65 64 20  ized VFSes need 
9200: 74 68 69 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f  this signal in o
9210: 72 64 65 72 20 74 6f 20 6f 70 65 72 61 74 65 20  rder to operate 
9220: 63 6f 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65  correctly.** whe
9230: 6e 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  n [PRAGMA synchr
9240: 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73  onous | PRAGMA s
9250: 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20  ynchronous=OFF] 
9260: 69 73 20 73 65 74 2c 20 62 75 74 20 6d 6f 73 74  is set, but most
9270: 20 0a 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f   .** VFSes do no
9280: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
9290: 61 6c 20 61 6e 64 20 73 68 6f 75 6c 64 20 73 69  al and should si
92a0: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
92b0: 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70  is opcode..** Ap
92c0: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
92d0: 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69  d not call [sqli
92e0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
92f0: 28 29 5d 20 77 69 74 68 20 74 68 69 73 0a 2a 2a  ()] with this.**
9300: 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67   opcode as doing
9310: 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20   so may disrupt 
9320: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  the operation of
9330: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
9340: 20 56 46 53 65 73 0a 2a 2a 20 74 68 61 74 20 64   VFSes.** that d
9350: 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a  o require it.  .
9360: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9370: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
9380: 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68  V_RETRY]].** ^Th
9390: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
93a0: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20  WIN32_AV_RETRY] 
93b0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
93c0: 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f  o configure auto
93d0: 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63  matic.** retry c
93e0: 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76  ounts and interv
93f0: 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20  als for certain 
9400: 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69  disk I/O operati
9410: 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77  ons for the.** w
9420: 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20  indows [VFS] in 
9430: 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65  order to provide
9440: 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74   robustness in t
9450: 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a  he presence of.*
9460: 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f  * anti-virus pro
9470: 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75  grams.  By defau
9480: 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20  lt, the windows 
9490: 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66  VFS will retry f
94a0: 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c  ile read,.** fil
94b0: 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c  e write, and fil
94c0: 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69  e delete operati
94d0: 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d  ons up to 10 tim
94e0: 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79  es, with a delay
94f0: 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73  .** of 25 millis
9500: 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68  econds before th
9510: 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e  e first retry an
9520: 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79  d with the delay
9530: 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62   increasing.** b
9540: 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20  y an additional 
9550: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9560: 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71  with each subseq
9570: 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69  uent retry.  Thi
9580: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f  s.** opcode allo
9590: 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c  ws these two val
95a0: 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20  ues (10 retries 
95b0: 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  and 25 milliseco
95c0: 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a  nds of delay).**
95d0: 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e   to be adjusted.
95e0: 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65    The values are
95f0: 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c   changed for all
9600: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
9610: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20  tions.** within 
9620: 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73  the same process
9630: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
9640: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
9650: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a  an array of two.
9660: 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72  ** integers wher
9670: 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65  e the first inte
9680: 67 65 72 20 69 20 74 68 65 20 6e 65 77 20 72 65  ger i the new re
9690: 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68  try count and th
96a0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65  e second.** inte
96b0: 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79  ger is the delay
96c0: 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74  .  If either int
96d0: 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eger is negative
96e0: 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69  , then the setti
96f0: 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  ng.** is not cha
9700: 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64  nged but instead
9710: 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
9720: 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67   of that setting
9730: 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69   is written.** i
9740: 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e  nto the array en
9750: 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68  try, allowing th
9760: 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20  e current retry 
9770: 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a  settings to be.*
9780: 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20  * interrogated. 
9790: 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72   The zDbName par
97a0: 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65  ameter is ignore
97b0: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
97c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
97d0: 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68  IST_WAL]].** ^Th
97e0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
97f0: 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63  PERSIST_WAL] opc
9800: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73  ode is used to s
9810: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a  et or query the.
9820: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57  ** persistent [W
9830: 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64  AL | Write Ahead
9840: 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20   Log] setting.  
9850: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
9860: 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69  auxiliary.** wri
9870: 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64  te ahead log and
9880: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66   shared memory f
9890: 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72  iles used for tr
98a0: 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
98b0: 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74  l.** are automat
98c0: 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77  ically deleted w
98d0: 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63  hen the latest c
98e0: 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65  onnection to the
98f0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f   database.** clo
9900: 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65  ses.  Setting pe
9910: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64  rsistent WAL mod
9920: 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66  e causes those f
9930: 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20  iles to persist 
9940: 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20  after.** close. 
9950: 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20   Persisting the 
9960: 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20  files is useful 
9970: 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65  when other proce
9980: 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  sses that do not
9990: 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70  .** have write p
99a0: 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65  ermission on the
99b0: 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61   directory conta
99c0: 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  ining the databa
99d0: 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20  se file want.** 
99e0: 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61  to read the data
99f0: 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68  base file, as th
9a00: 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64  e WAL and shared
9a10: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75   memory files mu
9a20: 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f  st exist.** in o
9a30: 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74  rder for the dat
9a40: 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64  abase to be read
9a50: 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74  able.  The fourt
9a60: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
9a70: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
9a80: 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74  control()] for t
9a90: 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c  his opcode shoul
9aa0: 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  d be a pointer t
9ab0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  o an integer..**
9ac0: 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73   That integer is
9ad0: 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65   0 to disable pe
9ae0: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64  rsistent WAL mod
9af0: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
9b00: 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57   persistent.** W
9b10: 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  AL mode.  If the
9b20: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20   integer is -1, 
9b30: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77  then it is overw
9b40: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
9b50: 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70  current.** WAL p
9b60: 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69  ersistence setti
9b70: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ng..**.** <li>[[
9b80: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
9b90: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
9ba0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
9bb0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
9bc0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70  FE_OVERWRITE] op
9bd0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
9be0: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
9bf0: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22  .** persistent "
9c00: 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72  powersafe-overwr
9c10: 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73  ite" or "PSOW" s
9c20: 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f  etting.  The PSO
9c30: 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74  W setting.** det
9c40: 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c  ermines the [SQL
9c50: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
9c60: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62  AFE_OVERWRITE] b
9c70: 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65  it of the.** xDe
9c80: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
9c90: 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65  ics methods. The
9ca0: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
9cb0: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
9cc0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9cd0: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
9ce0: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69   should be a poi
9cf0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
9d00: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65  er..** That inte
9d10: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61  ger is 0 to disa
9d20: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20  ble zero-damage 
9d30: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61  mode or 1 to ena
9d40: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a  ble zero-damage.
9d50: 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ** mode.  If the
9d60: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20   integer is -1, 
9d70: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77  then it is overw
9d80: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
9d90: 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d  current.** zero-
9da0: 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74  damage mode sett
9db0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
9dc0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
9dd0: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
9de0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9df0: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
9e00: 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  e is invoked by 
9e10: 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65  SQLite after ope
9e20: 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20  ning.** a write 
9e30: 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69  transaction to i
9e40: 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e  ndicate that, un
9e50: 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65  less it is rolle
9e60: 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a  d back for some.
9e70: 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65  ** reason, the e
9e80: 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66  ntire database f
9e90: 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72  ile will be over
9ea0: 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63  written by the c
9eb0: 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73  urrent .** trans
9ec0: 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20  action. This is 
9ed0: 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f  used by VACUUM o
9ee0: 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
9ef0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9f00: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a  NTL_VFSNAME]].**
9f10: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
9f20: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63  NTL_VFSNAME] opc
9f30: 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ode can be used 
9f40: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61  to obtain the na
9f50: 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56  mes of.** all [V
9f60: 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53  FSes] in the VFS
9f70: 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d   stack.  The nam
9f80: 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46  es are of all VF
9f90: 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a  S shims and the.
9fa0: 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d  ** final bottom-
9fb0: 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72  level VFS are wr
9fc0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
9fd0: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
9fe0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
9ff0: 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72  loc()] and the r
a000: 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20  esult is stored 
a010: 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  in the char* var
a020: 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68  iable.** that th
a030: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
a040: 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66  er of [sqlite3_f
a050: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70  ile_control()] p
a060: 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65  oints to..** The
a070: 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f   caller is respo
a080: 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69  nsible for freei
a090: 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68  ng the memory wh
a0a0: 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74  en done.  As wit
a0b0: 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f  h.** all file-co
a0c0: 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74  ntrol actions, t
a0d0: 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61  here is no guara
a0e0: 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77  ntee that this w
a0f0: 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20  ill actually.** 
a100: 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61  do anything.  Ca
a110: 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69  llers should ini
a120: 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72  tialize the char
a130: 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20  * variable to a 
a140: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
a150: 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c  in case this fil
a160: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74  e-control is not
a170: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54   implemented.  T
a180: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
a190: 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20  .** is intended 
a1a0: 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75  for diagnostic u
a1b0: 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c  se only..**.** <
a1c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
a1d0: 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57  L_PRAGMA]].** ^W
a1e0: 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d  henever a [PRAGM
a1f0: 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  A] statement is 
a200: 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49  parsed, an [SQLI
a210: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a220: 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f   .** file contro
a230: 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65  l is sent to the
a240: 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   open [sqlite3_f
a250: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72  ile] object corr
a260: 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20  esponding.** to 
a270: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
a280: 65 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70  e to which the p
a290: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
a2a0: 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67  refers. ^The arg
a2b0: 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20  ument.** to the 
a2c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a2d0: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
a2e0: 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ol is an array o
a2f0: 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  f.** pointers to
a300: 20 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a   strings (char**
a310: 29 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73  ) in which the s
a320: 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66  econd element of
a330: 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73   the array.** is
a340: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
a350: 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20   pragma and the 
a360: 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73  third element is
a370: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
a380: 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f   the.** pragma o
a390: 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72  r NULL if the pr
a3a0: 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75  agma has no argu
a3b0: 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64  ment.  ^The hand
a3c0: 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53  ler for an.** [S
a3d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a3e0: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
a3f0: 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20   can optionally 
a400: 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65  make the first e
a410: 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65  lement.** of the
a420: 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74   char** argument
a430: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69   point to a stri
a440: 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ng obtained from
a450: 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   [sqlite3_mprint
a460: 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65  f()].** or the e
a470: 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68  quivalent and th
a480: 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  at string will b
a490: 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74  ecome the result
a4a0: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f   of the pragma o
a4b0: 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d  r.** the error m
a4c0: 65 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72  essage if the pr
a4d0: 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20  agma fails. ^If 
a4e0: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  the.** [SQLITE_F
a4f0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
a500: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
a510: 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  s [SQLITE_NOTFOU
a520: 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c  ND], then normal
a530: 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72   .** [PRAGMA] pr
a540: 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75  ocessing continu
a550: 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51  es.  ^If the [SQ
a560: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a570: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  A].** file contr
a580: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ol returns [SQLI
a590: 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65  TE_OK], then the
a5a0: 20 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20   parser assumes 
a5b0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20  that the.** VFS 
a5c0: 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20  has handled the 
a5d0: 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e  PRAGMA itself an
a5e0: 64 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e  d the parser gen
a5f0: 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a  erates a no-op.*
a600: 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
a610: 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 5b  ment.  ^If the [
a620: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a630: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
a640: 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  l returns.** any
a650: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68   result code oth
a660: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
a670: 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  OK] or [SQLITE_N
a680: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d  OTFOUND], that m
a690: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65  eans.** that the
a6a0: 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64   VFS encountered
a6b0: 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20   an error while 
a6c0: 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52  handling the [PR
a6d0: 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a  AGMA] and the.**
a6e0: 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20   compilation of 
a6f0: 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73  the PRAGMA fails
a700: 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
a710: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a720: 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66  NTL_PRAGMA].** f
a730: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75  ile control occu
a740: 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e  rs at the beginn
a750: 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74  ing of pragma st
a760: 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73  atement analysis
a770: 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73   and so.** it is
a780: 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64   able to overrid
a790: 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47  e built-in [PRAG
a7a0: 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  MA] statements..
a7b0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a7c0: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
a7d0: 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  DLER]].** ^The [
a7e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
a7f0: 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c  YHANDLER].** fil
a800: 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65  e-control may be
a810: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a820: 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  te on the databa
a830: 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a  se file handle.*
a840: 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20  * shortly after 
a850: 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  it is opened in 
a860: 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65  order to provide
a870: 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69   a custom VFS wi
a880: 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  th access.** to 
a890: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  the connections 
a8a0: 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c  busy-handler cal
a8b0: 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d  lback. The argum
a8c0: 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 28  ent is of type (
a8d0: 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e  void **).** - an
a8e0: 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76   array of two (v
a8f0: 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54  oid *) values. T
a900: 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a  he first (void *
a910: 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74  ) actually point
a920: 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69  s.** to a functi
a930: 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20  on of type (int 
a940: 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e  (*)(void *)). In
a950: 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65   order to invoke
a960: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
a970: 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  .** busy-handler
a980: 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  , this function 
a990: 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65  should be invoke
a9a0: 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e  d with the secon
a9b0: 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a  d (void *) in.**
a9c0: 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74 68   the array as th
a9d0: 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e  e only argument.
a9e0: 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e   If it returns n
a9f0: 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  on-zero, then th
aa00: 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73  e operation.** s
aa10: 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 64  hould be retried
aa20: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
aa30: 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d  zero, the custom
aa40: 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e   VFS should aban
aa50: 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65  don the.** curre
aa60: 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a  nt operation..**
aa70: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
aa80: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
aa90: 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63  AME]].** ^Applic
aaa0: 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65  ation can invoke
aab0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
aac0: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
aad0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
aae0: 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20   to have SQLite 
aaf0: 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65  generate a.** te
ab00: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
ab10: 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
ab20: 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69  algorithm that i
ab30: 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65  s followed to ge
ab40: 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  nerate.** tempor
ab50: 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f  ary filenames fo
ab60: 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e  r TEMP tables an
ab70: 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  d other internal
ab80: 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61   uses.  The.** a
ab90: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
aba0: 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68  e a char** which
abb0: 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20   will be filled 
abc0: 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d  with the filenam
abd0: 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74  e.** written int
abe0: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
abf0: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
ac00: 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20  malloc()].  The 
ac10: 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a  caller should.**
ac20: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
ac30: 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20  _free()] on the 
ac40: 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20  result to avoid 
ac50: 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a  a memory leak..*
ac60: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
ac70: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
ac80: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
ac90: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
aca0: 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ZE] file control
acb0: 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65 72   is used to quer
acc0: 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20  y or set the.** 
acd0: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
ace0: 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69 6c  f bytes that wil
acf0: 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65  l be used for me
ad00: 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e  mory-mapped I/O.
ad10: 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
ad20: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
ad30: 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65   a value of type
ad40: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74   sqlite3_int64 t
ad50: 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76  hat.** is an adv
ad60: 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75  isory maximum nu
ad70: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
ad80: 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d   the file to mem
ad90: 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a  ory map.  The.**
ada0: 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72   pointer is over
adb0: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
adc0: 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65   old value.  The
add0: 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68   limit is not ch
ade0: 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20  anged if.** the 
adf0: 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79  value originally
ae00: 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e   pointed to is n
ae10: 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20  egative, and so 
ae20: 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69  the current limi
ae30: 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65  t .** can be que
ae40: 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ried by passing 
ae50: 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  in a pointer to 
ae60: 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
ae70: 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65  r.  This.** file
ae80: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64  -control is used
ae90: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69   internally to i
aea0: 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41  mplement [PRAGMA
aeb0: 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a   mmap_size]..**.
aec0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
aed0: 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a  FCNTL_TRACE]].**
aee0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
aef0: 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63  TL_TRACE] file c
af00: 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20  ontrol provides 
af10: 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61  advisory informa
af20: 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56  tion.** to the V
af30: 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74 68  FS about what th
af40: 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73 20  e higher layers 
af50: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73 74  of the SQLite st
af60: 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a  ack are doing..*
af70: 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74  * This file cont
af80: 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20 73  rol is used by s
af90: 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74 79  ome VFS activity
afa0: 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d   tracing [shims]
afb0: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
afc0: 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t is a zero-term
afd0: 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20  inated string.  
afe0: 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e  Higher layers in
aff0: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73   the.** SQLite s
b000: 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74  tack may generat
b010: 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74  e instances of t
b020: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
b030: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49   if.** the [SQLI
b040: 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41  TE_USE_FCNTL_TRA
b050: 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  CE] compile-time
b060: 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c   option is enabl
b070: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a  ed..**.** </ul>.
b080: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
b090: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
b0a0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
b0b0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
b0c0: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
b0d0: 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 32  LE             2
b0e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b0f0: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
b100: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a  E             3.
b110: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
b120: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
b130: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23               4.#
b140: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b150: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20  NTL_SIZE_HINT   
b160: 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
b170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b180: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20  TL_CHUNK_SIZE   
b190: 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
b1a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b1b0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20  L_FILE_POINTER  
b1c0: 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
b1d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b1e0: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20  _SYNC_OMITTED   
b1f0: 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69           8.#defi
b200: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b210: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20  WIN32_AV_RETRY  
b220: 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
b230: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
b240: 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20  ERSIST_WAL      
b250: 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65        10.#define
b260: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56   SQLITE_FCNTL_OV
b270: 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20  ERWRITE         
b280: 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20       11.#define 
b290: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
b2a0: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20  NAME            
b2b0: 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53      12.#define S
b2c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
b2d0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
b2e0: 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51     13.#define SQ
b2f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
b300: 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
b310: 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    14.#define SQL
b320: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
b330: 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20  NDLER           
b340: 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   15.#define SQLI
b350: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
b360: 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  ENAME           
b370: 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  16.#define SQLIT
b380: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
b390: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
b3a0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
b3b0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20  _FCNTL_TRACE    
b3c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
b3d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
b3e0: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
b3f0: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
b400: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
b410: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
b420: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
b430: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
b440: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
b450: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
b460: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
b470: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
b480: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
b490: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
b4a0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
b4b0: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
b4c0: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
b4d0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
b4e0: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
b4f0: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
b500: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
b510: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
b520: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
b530: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
b540: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
b550: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
b560: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
b570: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
b580: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
b590: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
b5a0: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
b5b0: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
b5c0: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
b5d0: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
b5e0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
b5f0: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
b600: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
b610: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
b620: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
b630: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
b640: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20  ystem".  See.** 
b650: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64  the [VFS | VFS d
b660: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
b670: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d  r further inform
b680: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
b690: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56   value of the iV
b6a0: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
b6b0: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
b6c0: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e  may be larger in
b6d0: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69  .** future versi
b6e0: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ons of SQLite.  
b6f0: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
b700: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
b710: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  d to this.** obj
b720: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65  ect when the iVe
b730: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69  rsion value is i
b740: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20  ncreased.  Note 
b750: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75  that the structu
b760: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  re.** of the sql
b770: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
b780: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74  changes in the t
b790: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65  ransaction betwe
b7a0: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  en.** SQLite ver
b7b0: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33  sion 3.5.9 and 3
b7c0: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65  .6.0 and yet the
b7d0: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
b7e0: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66  was not.** modif
b7f0: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ied..**.** The s
b800: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
b810: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
b820: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
b830: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
b840: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
b850: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
b860: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
b870: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
b880: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
b890: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
b8a0: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
b8b0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
b8c0: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
b8d0: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
b8e0: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
b8f0: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
b900: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
b910: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
b920: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
b930: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
b940: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
b950: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
b960: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
b970: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
b980: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
b990: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
b9a0: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72  e list.  Neither
b9b0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
b9c0: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46   code nor the VF
b9d0: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  S.** implementat
b9e0: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ion should use t
b9f0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
ba00: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
ba10: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
ba20: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
ba30: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
ba40: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
ba50: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
ba60: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
ba70: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
ba80: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
ba90: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
baa0: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
bab0: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
bac0: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
bad0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
bae0: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
baf0: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
bb00: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
bb10: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
bb20: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
bb30: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
bb40: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
bb50: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
bb60: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
bb70: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
bb80: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
bb90: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
bba0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  es..**.** [[sqli
bbb0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a  te3_vfs.xOpen]].
bbc0: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
bbd0: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a  ntees that the z
bbe0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
bbf0: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
bc00: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
bc10: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
bc20: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
bc30: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
bc40: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f  () with an optio
bc50: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64  nal suffix added
bc60: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69  ..** ^If a suffi
bc70: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68  x is added to th
bc80: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
bc90: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a  meter, it will.*
bca0: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73  * consist of a s
bcb0: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63  ingle "-" charac
bcc0: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  ter followed by 
bcd0: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20  no more than.** 
bce0: 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  11 alphanumeric 
bcf0: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61  and/or "-" chara
bd00: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  cters..** ^SQLit
bd10: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e  e further guaran
bd20: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  tees that.** the
bd30: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
bd40: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
bd50: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
bd60: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
bd70: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
bd80: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
bd90: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
bda0: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
bdb0: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
bdc0: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
bdd0: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
bde0: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
bdf0: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
be00: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
be10: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
be20: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
be30: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
be40: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
be50: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20  .** must invent 
be60: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
be70: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
be80: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20  ile.  ^Whenever 
be90: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d  the .** xFilenam
bea0: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  e parameter is N
beb0: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f  ULL it will also
bec0: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
bed0: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70  t the.** flags p
bee0: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e  arameter will in
bef0: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
bf00: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
bf10: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  ]..**.** The fla
bf20: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
bf30: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20  Open() includes 
bf40: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a  all bits set in.
bf50: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  ** the flags arg
bf60: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
bf70: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f  3_open_v2()].  O
bf80: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r if [sqlite3_op
bf90: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  en()].** or [sql
bfa0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69  ite3_open16()] i
bfb0: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
bfc0: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c  gs includes at l
bfd0: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  east.** [SQLITE_
bfe0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
bff0: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
c000: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78  REATE]. .** If x
c010: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
c020: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
c030: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
c040: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
c050: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
c060: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
c070: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
c080: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74  Flags may be set
c090: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65  ..**.** ^(SQLite
c0a0: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
c0b0: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
c0c0: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
c0d0: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
c0e0: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
c0f0: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
c100: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
c110: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
c120: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
c130: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
c140: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
c150: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
c160: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
c170: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
c180: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
c190: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
c1a0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
c1b0: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
c1c0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
c1d0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
c1e0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
c1f0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
c200: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
c210: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a  QLITE_OPEN_WAL].
c220: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
c230: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
c240: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
c250: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
c260: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
c270: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
c280: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
c290: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
c2a0: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
c2b0: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
c2c0: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
c2d0: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
c2e0: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
c2f0: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
c300: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
c310: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
c320: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
c330: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
c340: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
c350: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
c360: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
c370: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
c380: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
c390: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
c3a0: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
c3b0: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
c3c0: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
c3d0: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
c3e0: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
c3f0: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
c400: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
c410: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
c420: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
c430: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
c440: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
c450: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
c460: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
c470: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
c480: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
c490: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
c4a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
c4b0: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
c4c0: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
c4d0: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
c4e0: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  l>.**.** The [SQ
c4f0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
c500: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
c510: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
c520: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
c530: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
c540: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  sed.  ^The [SQLI
c550: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
c560: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
c570: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64  e set for TEMP d
c580: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65  atabases and the
c590: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61  ir journals, tra
c5a0: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61  nsient.** databa
c5b0: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72  ses, and subjour
c5c0: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nals..**.** ^The
c5d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
c5e0: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73  CLUSIVE] flag is
c5f0: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20   always used in 
c600: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  conjunction.** w
c610: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
c620: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61  OPEN_CREATE] fla
c630: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74  g, which are bot
c640: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e  h directly.** an
c650: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f  alogous to the O
c660: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41  _EXCL and O_CREA
c670: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50  T flags of the P
c680: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41  OSIX open().** A
c690: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  PI.  The SQLITE_
c6a0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66  OPEN_EXCLUSIVE f
c6b0: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64  lag, when paired
c6c0: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
c6d0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
c6e0: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64  , is used to ind
c6f0: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20  icate that file 
c700: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a  should always.**
c710: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64   be created, and
c720: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65   that it is an e
c730: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61  rror if it alrea
c740: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74  dy exists..** It
c750: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75   is <i>not</i> u
c760: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
c770: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
c780: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f  be opened .** fo
c790: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
c7a0: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65  ss..**.** ^At le
c7b0: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
c7c0: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
c7d0: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
c7e0: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
c7f0: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
c800: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
c810: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
c820: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
c830: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70   xOpen.  The xOp
c840: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
c850: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
c860: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
c870: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
c880: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
c890: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74    Note that.** t
c8a0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
c8b0: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c  must set the sql
c8c0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
c8d0: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ds to either.** 
c8e0: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33  a valid [sqlite3
c8f0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
c900: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20  ect or to NULL. 
c910: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a   xOpen must do.*
c920: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74  * this even if t
c930: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20  he open fails.  
c940: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74  SQLite expects t
c950: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hat the sqlite3_
c960: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a  file.pMethods.**
c970: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65   element will be
c980: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70   valid after xOp
c990: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72  en returns regar
c9a0: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
c9b0: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75  cess.** or failu
c9c0: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20  re of the xOpen 
c9d0: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  call..**.** [[sq
c9e0: 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73  lite3_vfs.xAcces
c9f0: 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67  s]].** ^The flag
ca00: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41  s argument to xA
ca10: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b  ccess() may be [
ca20: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
ca30: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  ISTS].** to test
ca40: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e   for the existen
ca50: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72  ce of a file, or
ca60: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
ca70: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a  READWRITE] to.**
ca80: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
ca90: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
caa0: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f   and writable, o
cab0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
cac0: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73  _READ].** to tes
cad0: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
cae0: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61   is at least rea
caf0: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c  dable.   The fil
cb00: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69  e can be a.** di
cb10: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  rectory..**.** ^
cb20: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
cb30: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
cb40: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
cb50: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
cb60: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
cb70: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
cb80: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
cb90: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
cba0: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
cbb0: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
cbc0: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
cbd0: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
cbe0: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
cbf0: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
cc00: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
cc10: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
cc20: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
cc30: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
cc40: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
cc50: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
cc60: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
cc70: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
cc80: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
cc90: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
cca0: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
ccb0: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
ccc0: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
ccd0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
cce0: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78  s(), xSleep(), x
ccf0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61  CurrentTime(), a
cd00: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  nd xCurrentTimeI
cd10: 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66  nt64().** interf
cd20: 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72  aces are not str
cd30: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
cd40: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
cd50: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
cd60: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
cd70: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
cd80: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
cd90: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
cda0: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
cdb0: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
cdc0: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
cdd0: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
cde0: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
cdf0: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
ce00: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
ce10: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
ce20: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
ce30: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
ce40: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28  ..** The xSleep(
ce50: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  ) method causes 
ce60: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
ce70: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
ce80: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
ce90: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
cea0: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e  econds given.  ^
ceb0: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
cec0: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
ced0: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
cee0: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
cef0: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
cf00: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66  d time as.** a f
cf10: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
cf20: 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75  lue..** ^The xCu
cf30: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
cf40: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c   method returns,
cf50: 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20   as an integer, 
cf60: 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61  the Julian.** Da
cf70: 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c  y Number multipl
cf80: 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  ied by 86400000 
cf90: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
cfa0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
cfb0: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
cfc0: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
cfd0: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
cfe0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
cff0: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
d000: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
d010: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
d020: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
d030: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
d040: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
d050: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
d060: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
d070: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
d080: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
d090: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
d0a0: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
d0b0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
d0c0: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
d0d0: 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73  .** ^The xSetSys
d0e0: 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53  temCall(), xGetS
d0f0: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64  ystemCall(), and
d100: 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c   xNestSystemCall
d110: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
d120: 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79   are not used by
d130: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
d140: 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61  .  These optiona
d150: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
d160: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20   provided.** by 
d170: 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61  some VFSes to fa
d180: 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67  cilitate testing
d190: 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65   of the VFS code
d1a0: 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20  . By overriding 
d1b0: 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73  .** system calls
d1c0: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20   with functions 
d1d0: 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f  under its contro
d1e0: 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61  l, a test progra
d1f0: 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74  m can.** simulat
d200: 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72  e faults and err
d210: 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68  or conditions th
d220: 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69  at would otherwi
d230: 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a  se be difficult.
d240: 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65  ** or impossible
d250: 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65   to induce.  The
d260: 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63   set of system c
d270: 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65  alls that can be
d280: 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76   overridden.** v
d290: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56  aries from one V
d2a0: 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61  FS to another, a
d2b0: 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73  nd from one vers
d2c0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ion of the same 
d2d0: 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  VFS to the.** ne
d2e0: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
d2f0: 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65  s that use these
d300: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74   interfaces must
d310: 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72   be prepared for
d320: 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f   any.** or all o
d330: 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  f these interfac
d340: 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72  es to be NULL or
d350: 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76   for their behav
d360: 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a  ior to change.**
d370: 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73   from one releas
d380: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20  e to the next.  
d390: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73  Applications mus
d3a0: 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f  t not attempt to
d3b0: 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f   access.** any o
d3c0: 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20  f these methods 
d3d0: 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  if the iVersion 
d3e0: 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65  of the VFS is le
d3f0: 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79  ss than 3..*/.ty
d400: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
d410: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
d420: 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f  _vfs;.typedef vo
d430: 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73  id (*sqlite3_sys
d440: 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b  call_ptr)(void);
d450: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
d460: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
d470: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
d480: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
d490: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75  rsion number (cu
d4a0: 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20  rrently 3) */.  
d4b0: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
d4c0: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
d4d0: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
d4e0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
d4f0: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
d500: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
d510: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
d520: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
d530: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
d540: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
d550: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
d560: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
d570: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
d580: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
d590: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
d5a0: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
d5b0: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
d5c0: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
d5d0: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
d5e0: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
d5f0: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
d600: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
d610: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
d620: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
d630: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
d640: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
d650: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
d660: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
d670: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
d680: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
d690: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
d6a0: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
d6b0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
d6c0: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c  Name, int flags,
d6d0: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
d6e0: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
d6f0: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
d700: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
d710: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
d720: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
d730: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
d740: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d750: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
d760: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
d770: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
d780: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
d790: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
d7a0: 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78  g);.  void (*(*x
d7b0: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
d7c0: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
d7d0: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29   char *zSymbol))
d7e0: 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28  (void);.  void (
d7f0: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74  *xDlClose)(sqlit
d800: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b  e3_vfs*, void*);
d810: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d  .  int (*xRandom
d820: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  ness)(sqlite3_vf
d830: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
d840: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
d850: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69  t (*xSleep)(sqli
d860: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69  te3_vfs*, int mi
d870: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69  croseconds);.  i
d880: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
d890: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
d8a0: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74   double*);.  int
d8b0: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72   (*xGetLastError
d8c0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d8d0: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20  int, char *);.  
d8e0: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
d8f0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
d900: 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68   version 1 of th
d910: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
d920: 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74  ect.  ** definit
d930: 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74  ion.  Those that
d940: 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65   follow are adde
d950: 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f  d in version 2 o
d960: 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69  r later.  */.  i
d970: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
d980: 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f  eInt64)(sqlite3_
d990: 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  vfs*, sqlite3_in
d9a0: 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  t64*);.  /*.  **
d9b0: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
d9c0: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
d9d0: 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68  ns 1 and 2 of th
d9e0: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
d9f0: 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20  ect..  ** Those 
da00: 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65  below are for ve
da10: 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61  rsion 3 and grea
da20: 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ter..  */.  int 
da30: 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xSetSystemCall
da40: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
da50: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
da60: 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  e, sqlite3_sysca
da70: 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74  ll_ptr);.  sqlit
da80: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28  e3_syscall_ptr (
da90: 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xGetSystemCall)
daa0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
dab0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
dac0: 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  );.  const char 
dad0: 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61  *(*xNextSystemCa
dae0: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
daf0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
db00: 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  ame);.  /*.  ** 
db10: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
db20: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
db30: 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66  s 1 through 3 of
db40: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
db50: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77  object..  ** New
db60: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
db70: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72  ppended in figur
db80: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
db90: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
dba0: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
dbb0: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
dbc0: 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f  s happens. .  */
dbd0: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
dbe0: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
dbf0: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d  he xAccess VFS m
dc00: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
dc10: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
dc20: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
dc30: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
dc40: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
dc50: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
dc60: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
dc70: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  fs] object.  The
dc80: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
dc90: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
dca0: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
dcb0: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
dcc0: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
dcd0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
dce0: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
dcf0: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
dd00: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
dd10: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
dd20: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
dd30: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
dd40: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
dd50: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
dd60: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
dd70: 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20  named directory 
dd80: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
dd90: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a   and writable.**
dda0: 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   (in other words
ddb0: 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62  , if files can b
ddc0: 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64  e added, removed
ddd0: 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69  , and renamed wi
dde0: 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65  thin.** the dire
ddf0: 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53  ctory)..** The S
de00: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
de10: 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20  DWRITE constant 
de20: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65  is currently use
de30: 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a  d only by the.**
de40: 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
de50: 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20  ectory pragma], 
de60: 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c  though this coul
de70: 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  d change in a fu
de80: 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
de90: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69  of SQLite..** Wi
dea0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
deb0: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
dec0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
ded0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
dee0: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
def0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  .  The SQLITE_AC
df00: 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61  CESS_READ consta
df10: 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74  nt is.** current
df20: 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67  ly unused, thoug
df30: 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73  h it might be us
df40: 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72  ed in a future r
df50: 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
df60: 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
df70: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
df80: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
df90: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
dfa0: 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a  READWRITE 1   /*
dfb0: 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20   Used by PRAGMA 
dfc0: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
dfd0: 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tory */.#define 
dfe0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
dff0: 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55  AD      2   /* U
e000: 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  nused */../*.** 
e010: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
e020: 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b  for the xShmLock
e030: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
e040: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
e050: 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
e060: 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63   the various loc
e070: 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a  king operations.
e080: 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68  ** allowed by th
e090: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
e0a0: 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d of [sqlite3_io
e0b0: 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a  _methods].  The.
e0c0: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65  ** following are
e0d0: 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20   the only legal 
e0e0: 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20  combinations of 
e0f0: 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20  flags to the.** 
e100: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a  xShmLock method:
e110: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
e120: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
e130: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
e140: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
e150: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
e160: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
e170: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  XCLUSIVE.** <li>
e180: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
e190: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
e1a0: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
e1b0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
e1c0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
e1d0: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75  EXCLUSIVE.** </u
e1e0: 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e  l>.**.** When un
e1f0: 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d  locking, the sam
e200: 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c  e SHARED or EXCL
e210: 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20  USIVE flag must 
e220: 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a  be supplied as.*
e230: 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74  * was given no t
e240: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
e250: 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54   lock.  .**.** T
e260: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
e270: 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f  od can transitio
e280: 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  n between unlock
e290: 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72  ed and SHARED or
e2a0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  .** between unlo
e2b0: 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49  cked and EXCLUSI
e2c0: 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74  VE.  It cannot t
e2d0: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
e2e0: 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20  n SHARED.** and 
e2f0: 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64  EXCLUSIVE..*/.#d
e300: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
e310: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a  _UNLOCK       1.
e320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
e330: 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  HM_LOCK         
e340: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
e350: 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20  _SHM_SHARED     
e360: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
e370: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
e380: 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      8../*.** CAP
e390: 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78  I3REF: Maximum x
e3a0: 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a  ShmLock index.**
e3b0: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
e3c0: 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69   method on [sqli
e3d0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
e3e0: 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a  may use values.*
e3f0: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
e400: 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64  this upper bound
e410: 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22   as its "offset"
e420: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
e430: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
e440: 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74  ll never attempt
e450: 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72   to acquire or r
e460: 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b  elease a.** lock
e470: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73   outside of this
e480: 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e   range.*/.#defin
e490: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f  e SQLITE_SHM_NLO
e4a0: 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a  CK        8.../*
e4b0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
e4c0: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
e4d0: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
e4e0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
e4f0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
e500: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
e510: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
e520: 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c  brary.  ^The sql
e530: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
e540: 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c  routine.** deall
e550: 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75  ocates any resou
e560: 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61  rces that were a
e570: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
e580: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
e590: 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
e5a0: 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64  nes are designed
e5b0: 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65   to aid in proce
e5c0: 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
e5d0: 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77  n and.** shutdow
e5e0: 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79  n on embedded sy
e5f0: 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74  stems.  Workstat
e600: 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ion applications
e610: 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65   using.** SQLite
e620: 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74   normally do not
e630: 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20   need to invoke 
e640: 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
e650: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
e660: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
e670: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
e680: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
e690: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
e6a0: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
e6b0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e6c0: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
e6d0: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
e6e0: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
e6f0: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
e700: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
e710: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
e720: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
e730: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
e740: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
e750: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e  3_shutdown().  ^
e760: 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69  (Only an effecti
e770: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
e780: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
e790: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
e7a0: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
e7b0: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
e7c0: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
e7d0: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63  ops.)^.**.** A c
e7e0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
e7f0: 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20  hutdown() is an 
e800: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
e810: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
e820: 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  rst.** call to s
e830: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
e840: 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74  ) since the last
e850: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e860: 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a  ize().  ^(Only.*
e870: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  * an effective c
e880: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
e890: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61  hutdown() does a
e8a0: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74  ny deinitializat
e8b0: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65  ion..** All othe
e8c0: 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f  r valid calls to
e8d0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
e8e0: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73  n() are harmless
e8f0: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
e900: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
e910: 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66  tialize() interf
e920: 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ace is threadsaf
e930: 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73  e, but sqlite3_s
e940: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20  hutdown().** is 
e950: 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  not.  The sqlite
e960: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74  3_shutdown() int
e970: 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79  erface must only
e980: 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
e990: 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65  a.** single thre
e9a0: 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64  ad.  All open [d
e9b0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
e9c0: 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f  ons] must be clo
e9d0: 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f  sed and all.** o
e9e0: 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f  ther SQLite reso
e9f0: 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65  urces must be de
ea00: 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20  allocated prior 
ea10: 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  to invoking.** s
ea20: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
ea30: 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  )..**.** Among o
ea40: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71  ther things, ^sq
ea50: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ea60: 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  () will invoke.*
ea70: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
ea80: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
ea90: 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   ^sqlite3_shutdo
eaa0: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76  wn().** will inv
eab0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
eac0: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nd()..**.** ^The
ead0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
eae0: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
eaf0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
eb00: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
eb10: 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65   ^If for some re
eb20: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
eb30: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
eb40: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
eb50: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
eb60: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
eb70: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
eb80: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
eb90: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
eba0: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
ebb0: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
ebc0: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
ebd0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
ebe0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
ebf0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
ec00: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
ec10: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
ec20: 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
ec30: 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
ec40: 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
ec50: 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73  ion usually does
ec60: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20   not need to.** 
ec70: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
ec80: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
ec90: 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  ctly.  For examp
eca0: 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  le, [sqlite3_ope
ecb0: 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71  n()].** calls sq
ecc0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ecd0: 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65  () so the SQLite
ece0: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65   library will be
ecf0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
ed00: 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68  * initialized wh
ed10: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  en [sqlite3_open
ed20: 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66  ()] is called if
ed30: 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69   it has not be i
ed40: 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c  nitialized.** al
ed50: 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72  ready.  ^However
ed60: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
ed70: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
ed80: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
ed90: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
eda0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
edb0: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
edc0: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
edd0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ede0: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
edf0: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
ee00: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
ee10: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ee20: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
ee30: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
ee40: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
ee50: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
ee60: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
ee70: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
ee80: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
ee90: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
eea0: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
eeb0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
eec0: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
eed0: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
eee0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
eef0: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
ef00: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
ef10: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
ef20: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
ef30: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
ef40: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
ef50: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
ef60: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
ef70: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
ef80: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
ef90: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
efa0: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
efb0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
efc0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
efd0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
efe0: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
eff0: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
f000: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
f010: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
f020: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
f030: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
f040: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
f050: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
f060: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
f070: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
f080: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
f090: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
f0a0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
f0b0: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
f0c0: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
f0d0: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
f0e0: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
f0f0: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
f100: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
f110: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
f120: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
f130: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
f140: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
f150: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
f160: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
f170: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
f180: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
f190: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
f1a0: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
f1b0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
f1c0: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
f1d0: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
f1e0: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
f1f0: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
f200: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
f210: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
f220: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
f230: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
f240: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
f250: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
f260: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
f270: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
f280: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
f290: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
f2a0: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
f2b0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f2c0: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
f2d0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
f2e0: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
f2f0: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
f300: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
f310: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
f320: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
f330: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55  s compiled for U
f340: 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72  nix, Windows, or
f350: 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b   OS/2..** When [
f360: 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20  custom builds | 
f370: 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
f380: 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75  platforms].** (u
f390: 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
f3a0: 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d  _OS_OTHER=1] com
f3b0: 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
f3c0: 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61  ion) the applica
f3d0: 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
f3e0: 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
f3f0: 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  ementation for.*
f400: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
f410: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
f420: 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70  os_end().  An ap
f430: 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
f440: 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ed.** implementa
f450: 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
f460: 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c  os_init() or sql
f470: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
f480: 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51   must return [SQ
f490: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
f4a0: 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
f4b0: 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
f4c0: 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
f4d0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
f4e0: 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29  initialize(void)
f4f0: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68  ;.int sqlite3_sh
f500: 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e  utdown(void);.in
f510: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
f520: 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  t(void);.int sql
f530: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
f540: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
f550: 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
f560: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
f570: 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ry.**.** The sql
f580: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
f590: 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
f5a0: 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63  to make global c
f5b0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
f5c0: 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74  changes to SQLit
f5d0: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75  e in order to tu
f5e0: 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  ne SQLite to the
f5f0: 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
f600: 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
f610: 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61  ation.  The defa
f620: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
f630: 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  n is recommended
f640: 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70   for most.** app
f650: 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f  lications and so
f660: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
f670: 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63   usually not nec
f680: 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a  essary.  It is.*
f690: 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75  * provided to su
f6a0: 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69  pport rare appli
f6b0: 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75  cations with unu
f6c0: 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  sual needs..**.*
f6d0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
f6e0: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
f6f0: 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
f700: 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  fe.  The applica
f710: 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73  tion.** must ins
f720: 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65  ure that no othe
f730: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
f740: 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20  ces are invoked 
f750: 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65  by other.** thre
f760: 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65  ads while sqlite
f770: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75  3_config() is ru
f780: 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d  nning.  Furtherm
f790: 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ore, sqlite3_con
f7a0: 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  fig().** may onl
f7b0: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69  y be invoked pri
f7c0: 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e  or to library in
f7d0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69  itialization usi
f7e0: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  ng.** [sqlite3_i
f7f0: 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20  nitialize()] or 
f800: 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62  after shutdown b
f810: 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  y [sqlite3_shutd
f820: 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73  own()]..** ^If s
f830: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
f840: 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  is called after 
f850: 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
f860: 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72  ize()] and befor
f870: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  e.** [sqlite3_sh
f880: 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69  utdown()] then i
f890: 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51  t will return SQ
f8a0: 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20  LITE_MISUSE..** 
f8b0: 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
f8c0: 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e  hat ^sqlite3_con
f8d0: 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c  fig() can be cal
f8e0: 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  led as part of t
f8f0: 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
f900: 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69  tion of an appli
f910: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b  cation-defined [
f920: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
f930: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
f940: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
f950: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f960: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
f970: 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  * [configuration
f980: 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65   option] that de
f990: 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74  termines.** what
f9a0: 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c   property of SQL
f9b0: 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e  ite is to be con
f9c0: 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71  figured.  Subseq
f9d0: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a  uent arguments.*
f9e0: 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  * vary depending
f9f0: 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75   on the [configu
fa00: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a  ration option].*
fa10: 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
fa20: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
fa30: 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61  When a configura
fa40: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73  tion option is s
fa50: 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  et, sqlite3_conf
fa60: 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51  ig() returns [SQ
fa70: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66  LITE_OK]..** ^If
fa80: 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75   the option is u
fa90: 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65  nknown or SQLite
faa0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65   is unable to se
fab0: 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  t the option.** 
fac0: 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
fad0: 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  e returns a non-
fae0: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
faf0: 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
fb00: 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e  3_config(int, ..
fb10: 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
fb20: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64  REF: Configure d
fb30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
fb40: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ons.**.** The sq
fb50: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
fb60: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
fb70: 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66  sed to make conf
fb80: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
fb90: 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62  nges to a [datab
fba0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
fbb0: 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
fbc0: 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a  is similar to.**
fbd0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
fbe0: 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20  ()] except that 
fbf0: 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c  the changes appl
fc00: 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  y to a single.**
fc10: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
fc20: 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65  ction] (specifie
fc30: 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
fc40: 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20  rgument)..**.** 
fc50: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
fc60: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  ent to sqlite3_d
fc70: 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e  b_config(D,V,...
fc80: 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51  )  is the.** [SQ
fc90: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
fca0: 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67  OKASIDE | config
fcb0: 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20  uration verb] - 
fcc0: 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
fcd0: 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74  .** that indicat
fce0: 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f  es what aspect o
fcf0: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
fd00: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
fd10: 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e  eing configured.
fd20: 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61  .** Subsequent a
fd30: 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65  rguments vary de
fd40: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
fd50: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
fd60: 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20  b..**.** ^Calls 
fd70: 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
fd80: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51  nfig() return SQ
fd90: 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f  LITE_OK if and o
fda0: 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61  nly if.** the ca
fdb0: 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  ll is considered
fdc0: 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a   successful..*/.
fdd0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  int sqlite3_db_c
fde0: 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20  onfig(sqlite3*, 
fdf0: 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
fe00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
fe10: 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
fe20: 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
fe30: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
fe40: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
fe50: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
fe60: 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
fe70: 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
fe80: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
fe90: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
fea0: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
feb0: 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
fec0: 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
fed0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
fee0: 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
fef0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
ff00: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
ff10: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
ff20: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
ff30: 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
ff40: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
ff50: 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
ff60: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
ff70: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
ff80: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20  IG_GETMALLOC].  
ff90: 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20  .** By creating 
ffa0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
ffb0: 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
ffc0: 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
ffd0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
ffe0: 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
fff0: 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69  MALLOC]).** duri
10000 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
10010 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
10020 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
10030 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
10040 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10050 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53   subsystem for S
10060 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
10070 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64   all of its.** d
10080 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
10090 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
100a0 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
100b0 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b  s with several [
100c0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
100d0 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74  allocators].** t
100e0 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c  hat are perfectl
100f0 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74  y adequate for t
10100 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20  he overwhelming 
10110 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  majority of appl
10120 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20  ications.** and 
10130 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74  that this object
10140 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20   is only useful 
10150 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69  to a tiny minori
10160 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
10170 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69  ns.** with speci
10180 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c  alized memory al
10190 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65  location require
101a0 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a  ments.  This obj
101b0 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75  ect is.** also u
101c0 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
101d0 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20  ng of SQLite in 
101e0 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79  order to specify
101f0 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
10200 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
10210 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  tor that simulat
10220 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66  es memory out-of
10230 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f  -memory conditio
10240 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74  ns in.** order t
10250 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51  o verify that SQ
10260 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72  Lite recovers gr
10270 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75  acefully from su
10280 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73  ch.** conditions
10290 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c  ..**.** The xMal
102a0 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61  loc, xRealloc, a
102b0 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73  nd xFree methods
102c0 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20   must work like 
102d0 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c  the.** malloc(),
102e0 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66   realloc() and f
102f0 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20  ree() functions 
10300 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
10310 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20  d C library..** 
10320 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
10330 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  es that the seco
10340 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
10350 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c  * xRealloc is al
10360 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74  ways a value ret
10370 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72  urned by a prior
10380 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75   call to xRoundu
10390 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73  p..**.** xSize s
103a0 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  hould return the
103b0 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
103c0 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  of a memory allo
103d0 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f  cation.** previo
103e0 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
103f0 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52  om xMalloc or xR
10400 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c  ealloc.  The all
10410 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69  ocated size.** i
10420 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73  s always at leas
10430 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20  t as big as the 
10440 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62  requested size b
10450 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
10460 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75  ..**.** The xRou
10470 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75  ndup method retu
10480 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62  rns what would b
10490 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  e the allocated 
104a0 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d  size of.** a mem
104b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67  ory allocation g
104c0 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61  iven a particula
104d0 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  r requested size
104e0 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a  .  Most memory.*
104f0 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  * allocators rou
10500 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c  nd up memory all
10510 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73  ocations at leas
10520 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75  t to the next mu
10530 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20  ltiple.** of 8. 
10540 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73   Some allocators
10550 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c   round up to a l
10560 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  arger multiple o
10570 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20  r to a power of 
10580 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f  2..** Every memo
10590 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
105a0 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20  quest coming in 
105b0 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33  through [sqlite3
105c0 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72  _malloc()].** or
105d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
105e0 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73  c()] first calls
105f0 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78   xRoundup.  If x
10600 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20  Roundup returns 
10610 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73  0, .** that caus
10620 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  es the correspon
10630 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ding memory allo
10640 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a  cation to fail..
10650 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20  **.** The xInit 
10660 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a  method initializ
10670 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
10680 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78  locator.  For ex
10690 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
106a0 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
106b0 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
106c0 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
106d0 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
106e0 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
106f0 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
10700 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
10710 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
10720 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10730 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
10740 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
10750 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
10760 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
10770 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
10780 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
10790 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
107a0 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
107b0 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a  d xShutdown..**.
107c0 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20  ** SQLite holds 
107d0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
107e0 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d  X_STATIC_MASTER]
107f0 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69   mutex when it i
10800 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49  nvokes.** the xI
10810 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74  nit method, so t
10820 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
10830 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65  need not be thre
10840 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20  adsafe.  The.** 
10850 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
10860 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20   is only called 
10870 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68  from [sqlite3_sh
10880 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20  utdown()] so it 
10890 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64  does.** not need
108a0 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66   to be threadsaf
108b0 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61  e either.  For a
108c0 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73  ll other methods
108d0 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64  , SQLite.** hold
108e0 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
108f0 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20  TEX_STATIC_MEM] 
10900 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73  mutex as long as
10910 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
10920 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
10930 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
10940 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  option is turned
10950 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74   on (which.** it
10960 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20   is by default) 
10970 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f  and so the metho
10980 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ds are automatic
10990 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e  ally serialized.
109a0 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20  .** However, if 
109b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
109c0 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73  EMSTATUS] is dis
109d0 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  abled, then the 
109e0 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73  other.** methods
109f0 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
10a00 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65  afe or else make
10a10 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e   their own arran
10a20 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73  gements for.** s
10a30 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  erialization..**
10a40 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
10a50 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e  never invoke xIn
10a60 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f  it() more than o
10a70 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69  nce without an i
10a80 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61  ntervening.** ca
10a90 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28  ll to xShutdown(
10aa0 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
10ab0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
10ac0 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
10ad0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
10ae0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
10af0 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
10b00 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
10b10 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
10b20 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10b30 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
10b40 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
10b50 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
10b60 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
10b70 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
10b80 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
10b90 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
10ba0 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
10bb0 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
10bc0 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
10bd0 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
10be0 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
10bf0 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
10c00 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
10c10 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
10c20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
10c30 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
10c40 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
10c50 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
10c60 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
10c70 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
10c80 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
10c90 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
10ca0 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
10cb0 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
10cc0 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
10cd0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
10ce0 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
10cf0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
10d00 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
10d10 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
10d20 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
10d30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
10d40 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
10d50 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
10d60 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  : {configuration
10d70 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54   option}.**.** T
10d80 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
10d90 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
10da0 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
10db0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
10dc0 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
10dd0 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
10de0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
10df0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
10e00 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
10e10 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
10e20 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
10e30 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
10e40 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
10e50 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
10e60 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
10e70 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
10e80 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
10e90 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
10ea0 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
10eb0 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
10ec0 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
10ed0 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
10ee0 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
10ef0 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
10f00 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
10f10 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
10f20 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
10f30 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
10f40 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
10f50 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
10f60 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
10f70 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
10f80 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
10f90 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
10fa0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
10fb0 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  LETHREAD]] <dt>S
10fc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
10fd0 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
10fe0 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
10ff0 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
11000 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
11010 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
11020 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
11030 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c  g mode] to Singl
11040 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  e-thread.  In ot
11050 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
11060 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  sables.** all mu
11070 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20  texing and puts 
11080 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f  SQLite into a mo
11090 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20  de where it can 
110a0 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20  only be used.** 
110b0 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
110c0 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  ad.   ^If SQLite
110d0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
110e0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
110f0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
11100 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
11110 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
11120 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
11130 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
11140 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  e to change the 
11150 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
11160 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c   from its defaul
11170 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69  t.** value of Si
11180 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20  ngle-thread and 
11190 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  so [sqlite3_conf
111a0 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
111b0 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
111c0 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
111d0 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
111e0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
111f0 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  AD.** configurat
11200 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
11210 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11220 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
11230 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
11240 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
11250 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
11260 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
11270 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
11280 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
11290 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
112a0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
112b0 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64   to Multi-thread
112c0 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
112d0 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
112e0 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64  * mutexing on [d
112f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11300 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
11310 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
11320 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ects..** The app
11330 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70  lication is resp
11340 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69  onsible for seri
11350 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74  alizing access t
11360 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  o.** [database c
11370 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
11380 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
11390 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65  ents].  But othe
113a0 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65  r mutexes.** are
113b0 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74   enabled so that
113c0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
113d0 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61  safe to use in a
113e0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a   multi-threaded.
113f0 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61  ** environment a
11400 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f  s long as no two
11410 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74   threads attempt
11420 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
11430 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
11440 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65  nnection] at the
11450 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66   same time.  ^If
11460 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
11470 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
11480 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
11490 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
114a0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
114b0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
114c0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
114d0 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
114e0 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64  the Multi-thread
114f0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11500 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
11510 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
11520 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
11530 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
11540 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
11550 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
11560 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61  THREAD configura
11570 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
11580 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
11590 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
115a0 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ED]] <dt>SQLITE_
115b0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
115c0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
115d0 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
115e0 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
115f0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
11600 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
11610 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11620 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
11630 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
11640 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
11650 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
11660 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
11670 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
11680 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
11690 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
116a0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
116b0 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
116c0 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
116d0 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
116e0 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
116f0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
11700 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
11710 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
11720 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
11730 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
11740 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
11750 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
11760 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
11770 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
11780 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
11790 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
117a0 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
117b0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
117c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
117d0 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
117e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
117f0 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
11800 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
11810 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
11820 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
11830 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
11840 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11850 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
11860 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
11870 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
11880 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
11890 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
118a0 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
118b0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
118c0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
118d0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
118e0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
118f0 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
11900 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
11910 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
11920 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
11930 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
11940 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
11950 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  IG_MALLOC]] <dt>
11960 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
11970 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
11980 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
11990 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
119a0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
119b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
119c0 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
119d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
119e0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
119f0 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
11a00 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
11a10 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
11a20 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
11a30 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
11a40 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
11a50 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
11a60 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11a70 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
11a80 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
11a90 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
11aa0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
11ab0 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
11ac0 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
11ad0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
11ae0 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
11af0 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
11b00 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
11b10 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
11b20 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11b30 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d  NFIG_GETMALLOC]]
11b40 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
11b50 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
11b60 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
11b70 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
11b80 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
11b90 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
11ba0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
11bb0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
11bc0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
11bd0 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
11be0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
11bf0 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
11c00 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
11c10 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
11c20 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
11c30 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
11c40 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
11c50 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
11c60 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
11c70 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
11c80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
11c90 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
11ca0 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
11cb0 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
11cc0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
11cd0 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
11ce0 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
11cf0 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e  r example. </dd>
11d00 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11d10 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
11d20 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
11d30 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f  NFIG_MEMSTATUS</
11d40 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
11d50 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  s option takes s
11d60 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
11d70 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65  f type int, inte
11d80 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a  rpreted as a .**
11d90 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20   boolean, which 
11da0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
11db0 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69  les the collecti
11dc0 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c  on of memory all
11dd0 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74  ocation .** stat
11de0 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d  istics. ^(When m
11df0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11e00 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
11e10 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a  disabled, the .*
11e20 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  * following SQLi
11e30 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
11e40 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69  come non-operati
11e50 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a  onal:.**   <ul>.
11e60 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
11e70 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
11e80 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
11e90 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
11ea0 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c  water()].**   <l
11eb0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  i> [sqlite3_soft
11ec0 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d  _heap_limit64()]
11ed0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
11ee0 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a  te3_status()].**
11ef0 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d     </ul>)^.** ^M
11f00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11f10 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
11f20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
11f30 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65  lt unless SQLite
11f40 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
11f50 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46  with [SQLITE_DEF
11f60 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d  AULT_MEMSTATUS]=
11f70 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  0 in which case 
11f80 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
11f90 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
11fa0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
11fb0 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64  default..** </dd
11fc0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
11fd0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
11fe0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11ff0 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
12000 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
12010 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
12020 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
12030 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
12040 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
12050 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
12060 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72  .  There are thr
12070 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41  ee arguments:  A
12080 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79   pointer an 8-by
12090 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65  te.** aligned me
120a0 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d  mory buffer from
120b0 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74   which the scrat
120c0 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77  ch allocations w
120d0 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c  ill be.** drawn,
120e0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
120f0 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  h scratch alloca
12100 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  tion (sz),.** an
12110 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d the maximum nu
12120 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20  mber of scratch 
12130 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e  allocations (N).
12140 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75    The sz.** argu
12150 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d  ment must be a m
12160 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a  ultiple of 16..*
12170 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
12180 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70  ment must be a p
12190 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
121a0 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66  yte aligned buff
121b0 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  er.** of at leas
121c0 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
121d0 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
121e0 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d  te will use no m
121f0 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72  ore than two scr
12200 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72  atch buffers per
12210 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20   thread.  So.** 
12220 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20  N should be set 
12230 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70  to twice the exp
12240 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75  ected maximum nu
12250 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e  mber of threads.
12260 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
12270 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61   never require a
12280 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
12290 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61  that is more tha
122a0 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65  n 6.** times the
122b0 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73   database page s
122c0 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ize. ^If SQLite 
122d0 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69  needs needs addi
122e0 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63  tional.** scratc
122f0 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20  h memory beyond 
12300 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
12310 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75   by this configu
12320 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74  ration option, t
12330 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hen .** [sqlite3
12340 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20  _malloc()] will 
12350 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
12360 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65  n the memory nee
12370 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ded.</dd>.**.** 
12380 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12390 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e  PAGECACHE]] <dt>
123a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
123b0 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  GECACHE</dt>.** 
123c0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
123d0 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
123e0 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
123f0 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
12400 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  an use for.** th
12410 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
12420 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64  cache with the d
12430 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68  efault page cach
12440 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
12450 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
12460 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64  iguration should
12470 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20   not be used if 
12480 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
12490 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61  efine page.** ca
124a0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
124b0 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69  on is loaded usi
124c0 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  ng the SQLITE_CO
124d0 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74  NFIG_PCACHE2 opt
124e0 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ion..** There ar
124f0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
12500 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
12510 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38  : A pointer to 8
12520 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a  -byte aligned.**
12530 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a   memory, the siz
12540 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62  e of each page b
12550 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
12560 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
12570 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  ges (N)..** The 
12580 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  sz argument shou
12590 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f  ld be the size o
125a0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
125b0 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28  tabase page.** (
125c0 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
125d0 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33  etween 512 and 3
125e0 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74  2768) plus a lit
125f0 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61  tle extra for ea
12600 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65  ch.** page heade
12610 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65  r.  ^The page he
12620 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20  ader size is 20 
12630 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65  to 40 bytes depe
12640 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20  nding on.** the 
12650 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72  host architectur
12660 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c  e.  ^It is harml
12670 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20  ess, apart from 
12680 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72  the wasted memor
12690 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a  y,.** to make sz
126a0 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61   a little too la
126b0 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a  rge.  The first.
126c0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
126d0 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
126e0 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
126f0 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
12700 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
12710 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
12720 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
12730 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ded by the first
12740 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74   argument to sat
12750 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f  isfy its.** memo
12760 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65  ry needs for the
12770 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74   first N pages t
12780 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63  hat it adds to c
12790 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74  ache.  ^If addit
127a0 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
127b0 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
127c0 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
127d0 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
127e0 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65  this option, the
127f0 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73  n.** SQLite goes
12800 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
12810 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61  loc()] for the a
12820 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67  dditional storag
12830 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20  e space..** The 
12840 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66  pointer in the f
12850 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
12860 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64  st.** be aligned
12870 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
12880 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
12890 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
128a0 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
128b0 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64  be undefined.</d
128c0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
128d0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20  E_CONFIG_HEAP]] 
128e0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
128f0 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
12900 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
12910 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
12920 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
12930 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  r that SQLite wi
12940 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c  ll use.** for al
12950 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
12960 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12970 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20  on needs beyond 
12980 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a  those provided.*
12990 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45  * for by [SQLITE
129a0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
129b0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   and [SQLITE_CON
129c0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
129d0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
129e0 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e  ee arguments: An
129f0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
12a00 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
12a10 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75  emory,.** the nu
12a20 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
12a30 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66   the memory buff
12a40 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69  er, and the mini
12a50 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
12a60 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ize..** ^If the 
12a70 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
12a80 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
12a90 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  r) is NULL, then
12aa0 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a   SQLite reverts.
12ab0 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20  ** to using its 
12ac0 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
12ad0 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79  llocator (the sy
12ae0 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d  stem malloc() im
12af0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a  plementation),.*
12b00 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72  * undoing any pr
12b10 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ior invocation o
12b20 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
12b30 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74  _MALLOC].  ^If t
12b40 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69  he.** memory poi
12b50 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
12b60 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c   and either [SQL
12b70 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
12b80 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  S3] or.** [SQLIT
12b90 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35  E_ENABLE_MEMSYS5
12ba0 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74  ] are defined, t
12bb0 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74  hen the alternat
12bc0 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ive memory.** al
12bd0 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67  locator is engag
12be0 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c  ed to handle all
12bf0 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f   of SQLites memo
12c00 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
12c10 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  eds..** The firs
12c20 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
12c30 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d  emory pointer) m
12c40 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
12c50 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62  o an 8-byte.** b
12c60 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
12c70 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
12c80 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  f SQLite will be
12c90 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
12ca0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
12cb0 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61  ation size is ca
12cc0 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52  pped at 2**12. R
12cd0 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73  easonable values
12ce0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69  .** for the mini
12cf0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
12d00 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72  ize are 2**5 thr
12d10 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a  ough 2**8.</dd>.
12d20 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12d30 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64  ONFIG_MUTEX]] <d
12d40 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12d50 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
12d60 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
12d70 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
12d80 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
12d90 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
12da0 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
12db0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
12dc0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
12dd0 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
12de0 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
12df0 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
12e00 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
12e10 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
12e20 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74  ed in place.** t
12e30 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
12e40 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
12e50 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
12e60 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
12e70 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f  the.** content o
12e80 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
12e90 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
12ea0 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
12eb0 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
12ec0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
12ed0 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
12ee0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
12ef0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
12f00 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
12f10 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
12f20 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
12f30 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
12f40 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
12f50 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
12f60 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
12f70 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
12f80 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
12f90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12fa0 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
12fb0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
12fc0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12fd0 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
12fe0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
12ff0 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
13000 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13010 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  GETMUTEX]] <dt>S
13020 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
13030 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
13040 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
13050 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
13060 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
13070 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
13080 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
13090 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
130a0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
130b0 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20  ucture.  The.** 
130c0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
130d0 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
130e0 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
130f0 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
13100 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20  y defined mutex 
13110 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
13120 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
13130 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
13140 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
13150 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  utex allocation.
13160 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
13170 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20   a wrapper used 
13180 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75  to track mutex u
13190 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d  sage for perform
131a0 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e  ance.** profilin
131b0 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f  g or testing, fo
131c0 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66  r example.   ^If
131d0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
131e0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
131f0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
13200 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
13210 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
13220 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
13230 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
13240 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
13250 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
13260 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
13270 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
13280 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
13290 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
132a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
132b0 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  TMUTEX configura
132c0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
132d0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
132e0 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
132f0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13300 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
13310 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13320 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
13330 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
13340 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
13350 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  wo arguments tha
13360 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
13370 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72  default.** memor
13380 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
13390 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
133a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
133b0 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  on each.** [data
133c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
133d0 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67  .  The first arg
133e0 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
133f0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
13400 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
13410 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
13420 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
13430 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
13440 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
13450 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13460 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74  n.)^  ^(This opt
13470 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
13480 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c  <i>default</i> l
13490 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54  ookaside size. T
134a0 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  he [SQLITE_DBCON
134b0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a  FIG_LOOKASIDE].*
134c0 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74  * verb to [sqlit
134d0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
134e0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
134f0 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
13500 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ide.** configura
13510 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
13520 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29  al connections.)
13530 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
13540 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
13550 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
13560 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
13570 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
13580 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
13590 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
135a0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
135b0 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e  pointer to.** an
135c0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
135d0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
135e0 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
135f0 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e  specifies the in
13600 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20  terface.** to a 
13610 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
13620 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
13630 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
13640 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
13650 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75  .** object and u
13660 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20  ses it for page 
13670 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  cache memory all
13680 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a  ocations.</dd>.*
13690 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
136a0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d  NFIG_GETPCACHE2]
136b0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
136c0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f  FIG_GETPCACHE2</
136d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
136e0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
136f0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
13700 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
13710 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
13720 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
13730 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20  thods2] object. 
13740 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f   SQLite copies o
13750 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
13760 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
13770 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20  ementation into 
13780 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c  that object.)^ <
13790 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
137a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d  ITE_CONFIG_LOG]]
137b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
137c0 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  IG_LOG</dt>.** <
137d0 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43  dd> The SQLITE_C
137e0 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
137f0 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66   is used to conf
13800 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65  igure the SQLite
13810 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f  .** global [erro
13820 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65  r log]..** (^The
13830 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
13840 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OG option takes 
13850 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61  two arguments: a
13860 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a   pointer to a.**
13870 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
13880 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20   call signature 
13890 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  of void(*)(void*
138a0 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
138b0 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69  ), .** and a poi
138c0 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49  nter to void. ^I
138d0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  f the function p
138e0 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
138f0 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76  LL, it is.** inv
13900 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oked by [sqlite3
13910 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65  _log()] to proce
13920 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20  ss each logging 
13930 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
13940 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  ** function poin
13950 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ter is NULL, the
13960 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
13970 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d   interface becom
13980 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e  es a no-op..** ^
13990 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72  The void pointer
139a0 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63   that is the sec
139b0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
139c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
139d0 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  G is.** passed t
139e0 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69  hrough as the fi
139f0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
13a00 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
13a10 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
13a20 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e  ** function when
13a30 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69  ever that functi
13a40 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  on is invoked.  
13a50 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
13a60 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
13a70 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20  logger function 
13a80 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
13a90 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
13aa0 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f   to the correspo
13ab0 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  nding.** [sqlite
13ac0 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e  3_log()] call an
13ad0 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  d is intended to
13ae0 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f   be a [result co
13af0 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78  de] or an.** [ex
13b00 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
13b10 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64  de].  ^The third
13b20 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65   parameter passe
13b30 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20  d to the logger 
13b40 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67  is.** log messag
13b50 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69  e after formatti
13b60 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f  ng via [sqlite3_
13b70 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20  snprintf()]..** 
13b80 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69  The SQLite loggi
13b90 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ng interface is 
13ba0 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74  not reentrant; t
13bb0 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
13bc0 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62  on.** supplied b
13bd0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
13be0 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b  n must not invok
13bf0 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
13c00 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20  erface..** In a 
13c10 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61  multi-threaded a
13c20 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20  pplication, the 
13c30 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
13c40 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
13c50 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74  nction must be t
13c60 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e  hreadsafe. </dd>
13c70 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13c80 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74  CONFIG_URI]] <dt
13c90 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  >SQLITE_CONFIG_U
13ca0 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 69 73  RI.** <dd>^(This
13cb0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
13cc0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
13cd0 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20  of type int. If 
13ce0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a  non-zero, then.*
13cf0 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  * URI handling i
13d00 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
13d10 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
13d20 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68  eter is zero, th
13d30 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a  en URI handling.
13d40 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ** is globally d
13d50 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55  isabled.)^ ^If U
13d60 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
13d70 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c  lobally enabled,
13d80 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a   all filenames.*
13d90 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  * passed to [sql
13da0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
13db0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
13dc0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
13dd0 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63  16()] or.** spec
13de0 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66  ified as part of
13df0 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e   [ATTACH] comman
13e00 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  ds are interpret
13e10 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61  ed as URIs, rega
13e20 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65  rdless.** of whe
13e30 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
13e40 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
13e50 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  ] flag is set wh
13e60 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  en the database.
13e70 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
13e80 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20   opened. ^If it 
13e90 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61  is globally disa
13ea0 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20  bled, filenames 
13eb0 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65  are.** only inte
13ec0 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20  rpreted as URIs 
13ed0 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50  if the SQLITE_OP
13ee0 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73  EN_URI flag is s
13ef0 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64  et when the.** d
13f00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13f10 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28  on is opened. ^(
13f20 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20  By default, URI 
13f30 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
13f40 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64  ally.** disabled
13f50 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  . The default va
13f60 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67  lue may be chang
13f70 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20  ed by compiling 
13f80 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
13f90 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d  ITE_USE_URI] sym
13fa0 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a  bol defined.)^.*
13fb0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13fc0 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
13fd0 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53  DEX_SCAN]] <dt>S
13fe0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
13ff0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
14000 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70  .** <dd>^This op
14010 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
14020 67 6c 65 20 69 6e 74 65 67 65 72 20 61 72 67 75  gle integer argu
14030 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e  ment which is in
14040 74 65 72 70 72 65 74 65 64 20 61 73 0a 2a 2a 20  terpreted as.** 
14050 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64  a boolean in ord
14060 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  er to enable or 
14070 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20  disable the use 
14080 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
14090 63 65 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c 20  ces for.** full 
140a0 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74  table scans in t
140b0 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a  he query optimiz
140c0 65 72 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c  er.  ^The defaul
140d0 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74  t setting is det
140e0 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68  ermined.** by th
140f0 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f  e [SQLITE_ALLOW_
14100 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
14110 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  CAN] compile-tim
14120 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20  e option, or is 
14130 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20  "on".** if that 
14140 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
14150 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a  ion is omitted..
14160 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74  ** The ability t
14170 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73  o disable the us
14180 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e  e of covering in
14190 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74  dices for full t
141a0 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73  able scans.** is
141b0 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e   because some in
141c0 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20  correctly coded 
141d0 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69  legacy applicati
141e0 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e  ons might malfun
141f0 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68  ction.** when th
14200 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69  e optimization i
14210 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76  s enabled.  Prov
14220 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74  iding the abilit
14230 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20  y to.** disable 
14240 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
14250 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65   allows the olde
14260 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61  r, buggy applica
14270 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72  tion code to wor
14280 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61  k.** without cha
14290 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65  nge even with ne
142a0 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
142b0 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  SQLite..**.** [[
142c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
142d0 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f  ACHE]] [[SQLITE_
142e0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
142f0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
14300 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61  _CONFIG_PCACHE a
14310 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  nd SQLITE_CONFIG
14320 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64  _GETPCACHE.** <d
14330 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73  d> These options
14340 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e   are obsolete an
14350 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  d should not be 
14360 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65  used by new code
14370 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65  ..** They are re
14380 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77  tained for backw
14390 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
143a0 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e  ty but are now n
143b0 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  o-ops..** </dd>.
143c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
143d0 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a  ONFIG_SQLLOG]].*
143e0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
143f0 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64  FIG_SQLLOG.** <d
14400 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  d>This option is
14410 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
14420 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d  if sqlite is com
14430 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
14440 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
14450 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f  _SQLLOG] pre-pro
14460 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66  cessor macro def
14470 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20  ined. The first 
14480 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a  argument should.
14490 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ** be a pointer 
144a0 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
144b0 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f   type void(*)(vo
144c0 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e  id*,sqlite3*,con
144d0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a  st char*, int)..
144e0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68  ** The second sh
144f0 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20  ould be of type 
14500 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c  (void*). The cal
14510 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
14520 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a   by the library.
14530 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61  ** in three sepa
14540 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63  rate circumstanc
14550 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62  es, identified b
14560 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73  y the value pass
14570 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  ed as the.** fou
14580 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49  rth parameter. I
14590 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
145a0 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65  ameter is 0, the
145b0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
145c0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73  onnection.** pas
145d0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
145e0 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a  d argument has j
145f0 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e  ust been opened.
14600 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
14610 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ent.** points to
14620 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69   a buffer contai
14630 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66  ning the name of
14640 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
14650 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a  se file. If the.
14660 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
14670 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74  ter is 1, then t
14680 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
14690 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20   that the third 
146a0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69  parameter.** poi
146b0 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20  nts to has just 
146c0 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f  been executed. O
146d0 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68  r, if the fourth
146e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c   parameter is 2,
146f0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e   then.** the con
14700 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61  nection being pa
14710 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
14720 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
14730 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68  being closed. Th
14740 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
14750 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e  eter is passed N
14760 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65  ULL In this case
14770 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66  .  An example of
14780 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63   using this.** c
14790 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
147a0 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20  ion can be seen 
147b0 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c  in the "test_sql
147c0 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69  log.c" source fi
147d0 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e  le in.** the can
147e0 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f  onical SQLite so
147f0 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a  urce tree.</dd>.
14800 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14810 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d  ONFIG_MMAP_SIZE]
14820 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
14830 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
14840 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f  .** <dd>^SQLITE_
14850 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
14860 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69   takes two 64-bi
14870 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74  t integer (sqlit
14880 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73  e3_int64) values
14890 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65  .** that are the
148a0 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69   default mmap si
148b0 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65  ze limit (the de
148c0 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f  fault setting fo
148d0 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61  r.** [PRAGMA mma
148e0 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65  p_size]) and the
148f0 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
14900 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
14910 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
14920 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65  t setting can be
14930 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65   overridden by e
14940 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
14950 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  nection using.**
14960 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41   either the [PRA
14970 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63  GMA mmap_size] c
14980 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73  ommand, or by us
14990 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ing the.** [SQLI
149a0 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
149b0 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ZE] file control
149c0 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d  .  ^(The maximum
149d0 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
149e0 7a 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20  ze.** cannot be 
149f0 63 68 61 6e 67 65 64 20 61 74 20 72 75 6e 2d 74  changed at run-t
14a00 69 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74 68  ime.  Nor may th
14a10 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
14a20 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 65  d mmap size.** e
14a30 78 63 65 65 64 20 74 68 65 20 63 6f 6d 70 69 6c  xceed the compil
14a40 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d  e-time maximum m
14a50 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20  map size set by 
14a60 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  the.** [SQLITE_M
14a70 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f  AX_MMAP_SIZE] co
14a80 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
14a90 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68  n.)^.** ^If eith
14aa0 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  er argument to t
14ab0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65  his option is ne
14ac0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61  gative, then tha
14ad0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  t argument is.**
14ae0 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20   changed to its 
14af0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66  compile-time def
14b00 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ault..**.** [[SQ
14b10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
14b20 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20  2_HEAPSIZE]].** 
14b30 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14b40 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
14b50 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70  .** <dd>^This op
14b60 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
14b70 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65  ilable if SQLite
14b80 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72   is compiled for
14b90 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 77 69 74 68   Windows.** with
14ba0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e   the [SQLITE_WIN
14bb0 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70  32_MALLOC] pre-p
14bc0 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64  rocessor macro d
14bd0 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c 49 54  efined..** SQLIT
14be0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
14bf0 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20  EAPSIZE takes a 
14c00 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  32-bit unsigned 
14c10 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a  integer value.**
14c20 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
14c30 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  the maximum size
14c40 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20   of the created 
14c50 68 65 61 70 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  heap..** </dl>.*
14c60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14c70 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
14c80 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
14c90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14ca0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
14cb0 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
14cc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14cd0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
14ce0 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
14cf0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
14d00 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
14d10 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
14d20 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
14d30 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
14d40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14d50 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
14d60 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
14d70 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
14d80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
14d90 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
14da0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
14db0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
14dc0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
14dd0 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
14de0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
14df0 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
14e00 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14e10 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
14e20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
14e30 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
14e40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14e50 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
14e60 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
14e70 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
14e80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
14e90 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
14ea0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
14eb0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
14ec0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14ed0 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
14ee0 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
14ef0 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
14f00 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
14f10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
14f20 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
14f30 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
14f40 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
14f50 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
14f60 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
14f70 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
14f80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
14f90 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
14fa0 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
14fb0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14fc0 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
14fd0 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  5  /* no-op */.#
14fe0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14ff0 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
15000 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
15010 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
15020 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
15030 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
15040 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
15050 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15060 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20  PCACHE2      18 
15070 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
15080 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
15090 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
150a0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
150b0 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65     19  /* sqlite
150c0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
150d0 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
150e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
150f0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
15100 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  20  /* int */.#d
15110 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15120 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20  FIG_SQLLOG      
15130 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c   21  /* xSqllog,
15140 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
15150 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15160 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20  MMAP_SIZE    22 
15170 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36   /* sqlite3_int6
15180 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  4, sqlite3_int64
15190 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
151a0 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
151b0 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33  HEAPSIZE      23
151c0 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a    /* int nByte *
151d0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
151e0 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
151f0 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61  ection Configura
15200 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a  tion Options.**.
15210 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
15220 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
15230 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
15240 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15250 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
15260 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
15270 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
15280 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
15290 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
152a0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
152b0 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
152c0 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
152d0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
152e0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
152f0 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
15300 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15310 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
15320 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
15330 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
15340 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
15350 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
15360 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
15370 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
15380 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
15390 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65  ll worked.  ^The
153a0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
153b0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
153c0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
153d0 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
153e0 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
153f0 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
15400 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
15410 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
15420 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
15430 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
15440 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
15450 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
15460 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
15470 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61  on takes three a
15480 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
15490 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
154a0 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b  ne the .** [look
154b0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
154c0 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72  ocator] configur
154d0 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64  ation for the [d
154e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
154f0 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  on]..** ^The fir
15500 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65  st argument (the
15510 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
15520 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
15530 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a  config()] is a.*
15540 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  * pointer to a m
15550 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
15560 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
15570 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68  e memory..** ^Th
15580 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
15590 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54   after the SQLIT
155a0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
155b0 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79  SIDE verb.** may
155c0 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63   be NULL in whic
155d0 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69  h case SQLite wi
155e0 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a  ll allocate the.
155f0 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ** lookaside buf
15600 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67  fer itself using
15610 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
15620 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ()]. ^The second
15630 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
15640 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
15650 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
15660 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68  r slot.  ^The th
15670 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
15680 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
15690 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a   slots.  The siz
156a0 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  e of the buffer 
156b0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
156c0 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72  ument must be gr
156d0 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72  eater than.** or
156e0 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72   equal to the pr
156f0 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63  oduct of the sec
15700 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72  ond and third ar
15710 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75  guments.  The bu
15720 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20  ffer.** must be 
15730 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
15740 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20  byte boundary.  
15750 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61  ^If the second a
15760 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51  rgument to.** SQ
15770 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
15780 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61  OKASIDE is not a
15790 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20   multiple of 8, 
157a0 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79  it is internally
157b0 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e  .** rounded down
157c0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61   to the next sma
157d0 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ller multiple of
157e0 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61   8.  ^(The looka
157f0 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63  side memory.** c
15800 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
15810 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
15820 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20  ection can only 
15830 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20  be changed when 
15840 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  that.** connecti
15850 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  on is not curren
15860 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73  tly using lookas
15870 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69  ide memory, or i
15880 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a  n other words.**
15890 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65   when the "curre
158a0 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e  nt value" return
158b0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
158c0 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b  3_db_status](D,[
158d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
158e0 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73  OKASIDE],...) is
158f0 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74   zero..** Any at
15900 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20  tempt to change 
15910 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
15920 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69  mory configurati
15930 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64  on when lookasid
15940 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69  e.** memory is i
15950 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65  n use leaves the
15960 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
15970 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74  nchanged and ret
15980 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  urns .** [SQLITE
15990 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  _BUSY].)^</dd>.*
159a0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
159b0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
159c0 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FKEY</dt>.** <dd
159d0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
159e0 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
159f0 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
15a00 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a  enforcement of.*
15a10 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  * [foreign key c
15a20 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68  onstraints].  Th
15a30 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
15a40 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
15a50 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
15a60 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
15a70 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
15a80 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
15a90 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
15aa0 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
15ab0 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72   enable FK enfor
15ac0 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69  cement or negati
15ad0 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65  ve to leave FK e
15ae0 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e  nforcement.** un
15af0 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65  changed.  The se
15b00 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
15b10 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
15b20 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
15b30 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
15b40 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
15b50 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b  icate whether FK
15b60 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20   enforcement is 
15b70 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c  off or on.** fol
15b80 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
15b90 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
15ba0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
15bb0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
15bc0 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
15bd0 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  the FK enforceme
15be0 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  nt setting is no
15bf0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
15c00 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
15c10 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
15c20 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c  _ENABLE_TRIGGER<
15c30 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
15c40 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
15c50 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
15c60 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54  isable [CREATE T
15c70 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
15c80 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  s]..** There sho
15c90 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
15ca0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
15cb0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
15cc0 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
15cd0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
15ce0 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67  to disable trigg
15cf0 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ers,.** positive
15d00 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67   to enable trigg
15d10 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ers or negative 
15d20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
15d30 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
15d40 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
15d50 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
15d60 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
15d70 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
15d80 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
15d90 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
15da0 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20  hether triggers 
15db0 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20  are disabled or 
15dc0 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  enabled.** follo
15dd0 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
15de0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
15df0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
15e00 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
15e10 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
15e20 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e  e trigger settin
15e30 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
15e40 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
15e50 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
15e60 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
15e70 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
15e80 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f       1001  /* vo
15e90 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23  id* int int */.#
15ea0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
15eb0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
15ec0 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20  EY     1002  /* 
15ed0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
15ee0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
15ef0 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
15f00 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74  ER  1003  /* int
15f10 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a   int* */.../*.**
15f20 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
15f30 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
15f40 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
15f50 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
15f60 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
15f70 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
15f80 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
15f90 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
15fa0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
15fb0 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
15fc0 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
15fd0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
15fe0 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
15ff0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
16000 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
16010 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
16020 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
16030 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
16040 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69  odes(sqlite3*, i
16050 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
16060 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74  * CAPI3REF: Last
16070 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a   Insert Rowid.**
16080 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20  .** ^Each entry 
16090 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74  in most SQLite t
160a0 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f  ables (except fo
160b0 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44  r [WITHOUT ROWID
160c0 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73  ] tables).** has
160d0 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74   a unique 64-bit
160e0 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67   signed.** integ
160f0 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68  er key called th
16100 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69  e [ROWID | "rowi
16110 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20  d"]. ^The rowid 
16120 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61  is always availa
16130 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64  ble.** as an und
16140 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e  eclared column n
16150 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c  amed ROWID, OID,
16160 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c   or _ROWID_ as l
16170 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20  ong as those.** 
16180 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c  names are not al
16190 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69  so used by expli
161a0 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
161b0 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74  olumns. ^If.** t
161c0 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63  he table has a c
161d0 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49  olumn of type [I
161e0 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
161f0 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f  EY] then that co
16200 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68  lumn.** is anoth
16210 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65  er alias for the
16220 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   rowid..**.** ^T
16230 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  he sqlite3_last_
16240 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20  insert_rowid(D) 
16250 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
16260 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
16270 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65   the .** most re
16280 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20  cent successful 
16290 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20  [INSERT] into a 
162a0 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b  rowid table or [
162b0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
162c0 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f  * on database co
162d0 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e  nnection D..** ^
162e0 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49  Inserts into [WI
162f0 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
16300 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63 6f  les are not reco
16310 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20  rded..** ^If no 
16320 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
16330 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20  RT]s into rowid 
16340 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65  tables.** have e
16350 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20  ver occurred on 
16360 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
16370 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74  nection D, .** t
16380 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  hen sqlite3_last
16390 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
163a0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
163b0 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e  *.** ^(If an [IN
163c0 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74  SERT] occurs wit
163d0 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72  hin a trigger or
163e0 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75   within a [virtu
163f0 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74  al table].** met
16400 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72  hod, then this r
16410 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75  outine will retu
16420 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  rn the [rowid] o
16430 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a  f the inserted.*
16440 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73  * row as long as
16450 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
16460 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65  virtual table me
16470 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e  thod is running.
16480 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65  .** But once the
16490 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
164a0 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  ual table method
164b0 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65   ends, the value
164c0 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79   returned .** by
164d0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
164e0 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74  verts to what it
164f0 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20   was before the 
16500 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
16510 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68  al.** table meth
16520 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a  od began.)^.**.*
16530 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  * ^An [INSERT] t
16540 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
16550 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
16560 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
16570 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
16580 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
16590 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
165a0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
165b0 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
165c0 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54  e.  ^Thus INSERT
165d0 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
165e0 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
165f0 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
16600 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
16610 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
16620 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
16630 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
16640 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
16650 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
16660 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65  on fails.  ^(Whe
16670 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
16680 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
16690 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
166a0 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
166b0 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
166c0 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
166d0 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
166e0 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
166f0 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
16700 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
16710 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
16720 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
16730 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
16740 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
16750 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
16760 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a   interface.)^.**
16770 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
16780 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f  poses of this ro
16790 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52  utine, an [INSER
167a0 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  T] is considered
167b0 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73   to.** be succes
167c0 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20  sful even if it 
167d0 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20  is subsequently 
167e0 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
167f0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
16800 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74   is accessible t
16810 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
16820 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73   via the.** [las
16830 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
16840 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
16850 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
16860 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f  ate thread perfo
16870 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52  rms a new [INSER
16880 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  T] on the same.*
16890 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
168a0 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
168b0 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
168c0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
168d0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
168e0 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
168f0 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
16900 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a  nsert [rowid],.*
16910 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  * then the value
16920 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
16930 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
16940 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
16950 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
16960 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
16970 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
16980 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
16990 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
169a0 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  id]..*/.sqlite3_
169b0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
169c0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
169d0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
169e0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
169f0 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
16a00 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
16a10 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
16a20 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
16a30 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73  umber of databas
16a40 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65  e rows that were
16a50 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69   changed.** or i
16a60 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
16a70 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
16a80 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
16a90 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  d SQL statement.
16aa0 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ** on the [datab
16ab0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
16ac0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
16ad0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
16ae0 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e  ..** ^(Only chan
16af0 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72  ges that are dir
16b00 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20  ectly specified 
16b10 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c  by the [INSERT],
16b20 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72   [UPDATE],.** or
16b30 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
16b40 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ent are counted.
16b50 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e    Auxiliary chan
16b60 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a  ges caused by.**
16b70 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f   triggers or [fo
16b80 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
16b90 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  s] are not count
16ba0 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a  ed.)^ Use the.**
16bb0 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
16bc0 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74  changes()] funct
16bd0 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ion to find the 
16be0 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
16bf0 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75  changes.** inclu
16c00 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75  ding changes cau
16c10 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20  sed by triggers 
16c20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20  and foreign key 
16c30 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  actions..**.** ^
16c40 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
16c50 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c  w that are simul
16c60 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54  ated by an [INST
16c70 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a  EAD OF trigger].
16c80 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ** are not count
16c90 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74  ed.  Only real t
16ca0 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65  able changes are
16cb0 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
16cc0 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22  ^(A "row change"
16cd0 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20   is a change to 
16ce0 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
16cf0 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a  a single table.*
16d00 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49  * caused by an I
16d10 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f  NSERT, DELETE, o
16d20 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
16d30 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a  nt.  Rows that.*
16d40 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73  * are changed as
16d50 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66   side effects of
16d60 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
16d70 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
16d80 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41  ,.** rollback, A
16d90 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
16da0 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f   [DROP TABLE], o
16db0 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a  r by any other.*
16dc0 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20  * mechanisms do 
16dd0 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72  not count as dir
16de0 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e  ect row changes.
16df0 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67  )^.**.** A "trig
16e00 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20  ger context" is 
16e10 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75  a scope of execu
16e20 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73  tion that begins
16e30 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74   and.** ends wit
16e40 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20  h the script of 
16e50 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  a [CREATE TRIGGE
16e60 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a  R | trigger]. .*
16e70 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65  * Most SQL state
16e80 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61  ments are.** eva
16e90 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f  luated outside o
16ea0 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20  f any trigger.  
16eb0 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70  This is the "top
16ec0 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67   level".** trigg
16ed0 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20  er context.  If 
16ee0 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20  a trigger fires 
16ef0 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76  from the top lev
16f00 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69  el, a.** new tri
16f10 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20  gger context is 
16f20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20  entered for the 
16f30 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74  duration of that
16f40 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e   one.** trigger.
16f50 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72    Subtriggers cr
16f60 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73  eate subcontexts
16f70 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74   for their durat
16f80 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ion..**.** ^Call
16f90 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ing [sqlite3_exe
16fa0 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
16fb0 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69  _step()] recursi
16fc0 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  vely does.** not
16fd0 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72   create a new tr
16fe0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
16ff0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
17000 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
17010 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74  number of direct
17020 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20   row changes in 
17030 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
17040 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
17050 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  E, or DELETE sta
17060 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
17070 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65  e same.** trigge
17080 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
17090 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c   ^Thus, when cal
170a0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  led from the top
170b0 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e   level, this fun
170c0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
170d0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
170e0 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
170f0 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
17100 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
17110 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f  ETE.** that also
17120 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65   occurred at the
17130 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57   top level.  ^(W
17140 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
17150 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20  f a trigger,.** 
17160 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
17170 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20  ges() interface 
17180 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f  can be called to
17190 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
171a0 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69   of.** changes i
171b0 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
171c0 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e  tly completed IN
171d0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
171e0 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65   DELETE.** state
171f0 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
17200 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65  body of the same
17210 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77   trigger..** How
17220 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72  ever, the number
17230 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e   returned does n
17240 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
17250 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  es.** caused by 
17260 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63  subtriggers sinc
17270 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65  e those have the
17280 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29  ir own context.)
17290 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
172a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
172b0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
172c0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
172d0 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
172e0 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
172f0 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
17300 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
17310 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
17320 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
17330 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
17340 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17350 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
17360 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
17370 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
17380 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
17390 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64  ned.** is unpred
173a0 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
173b0 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
173c0 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
173d0 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
173e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
173f0 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
17400 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
17410 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
17420 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
17430 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e  mber of row chan
17440 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49  ges caused by [I
17450 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41  NSERT],.** [UPDA
17460 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
17470 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65  statements since
17480 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
17490 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f  onnection] was o
174a0 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20  pened..** ^(The 
174b0 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62  count returned b
174c0 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  y sqlite3_total_
174d0 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64  changes() includ
174e0 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a  es all changes.*
174f0 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41  * from all [CREA
17500 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
17510 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61  gger] contexts a
17520 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  nd changes made 
17530 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  by.** [foreign k
17540 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77  ey actions]. How
17550 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75  ever,.** the cou
17560 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
17570 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64  ude changes used
17580 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52   to implement [R
17590 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
175a0 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62  nts,.** do rollb
175b0 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72  acks or ABORT pr
175c0 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52  ocessing, or [DR
175d0 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73  OP TABLE] proces
175e0 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f  sing.  The.** co
175f0 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
17600 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65  lude rows of vie
17610 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20  ws that fire an 
17620 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
17630 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20  ger],.** though 
17640 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f  if the INSTEAD O
17650 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20  F trigger makes 
17660 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f  changes of its o
17670 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65  wn, those change
17680 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65  s .** are counte
17690 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  d.)^.** ^The sql
176a0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
176b0 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f  es() function co
176c0 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73  unts the changes
176d0 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74   as soon as.** t
176e0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
176f0 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20  t makes them is 
17700 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20  completed (when 
17710 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
17720 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65  ndle.** is passe
17730 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  d to [sqlite3_re
17740 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
17750 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e  e3_finalize()]).
17760 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
17770 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
17780 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
17790 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
177a0 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
177b0 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c  , and the [total
177c0 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  _changes() SQL f
177d0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
177e0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
177f0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
17800 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
17810 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17820 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
17830 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
17840 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
17850 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
17860 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
17870 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
17880 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
17890 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
178a0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
178b0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
178c0 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
178d0 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
178e0 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e  ng Query.**.** ^
178f0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
17900 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
17910 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
17920 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
17930 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
17940 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
17950 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
17960 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
17970 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
17980 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
17990 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
179a0 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
179b0 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
179c0 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
179d0 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
179e0 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
179f0 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
17a00 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ly..**.** ^It is
17a10 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
17a20 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20  is routine from 
17a30 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65  a thread differe
17a40 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74  nt from the.** t
17a50 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75  hread that is cu
17a60 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20  rrently running 
17a70 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65  the database ope
17a80 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a  ration.  But it.
17a90 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  ** is not safe t
17aa0 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
17ab0 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61  ine with a [data
17ac0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17ad0 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73   that.** is clos
17ae0 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73  ed or might clos
17af0 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  e before sqlite3
17b00 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74  _interrupt() ret
17b10 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  urns..**.** ^If 
17b20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  an SQL operation
17b30 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20   is very nearly 
17b40 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20  finished at the 
17b50 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c  time when.** sql
17b60 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
17b70 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e   is called, then
17b80 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61   it might not ha
17b90 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74  ve an opportunit
17ba0 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72  y.** to be inter
17bb0 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74  rupted and might
17bc0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d   continue to com
17bd0 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  pletion..**.** ^
17be0 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
17bf0 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
17c00 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
17c10 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
17c20 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  PT]..** ^If the 
17c30 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20  interrupted SQL 
17c40 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20  operation is an 
17c50 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
17c60 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
17c70 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65  t is inside an e
17c80 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
17c90 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e  ion, then the en
17ca0 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  tire transaction
17cb0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c  .** will be roll
17cc0 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
17cd0 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cally..**.** ^Th
17ce0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
17cf0 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69  upt(D) call is i
17d00 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61  n effect until a
17d10 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  ll currently run
17d20 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
17d30 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62  ements on [datab
17d40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
17d50 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e  D complete.  ^An
17d60 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d  y new SQL statem
17d70 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
17d80 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
17d90 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
17da0 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20  rupt() call and 
17db0 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72  before the .** r
17dc0 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
17dd0 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  s reaches zero a
17de0 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  re interrupted a
17df0 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65  s if they had be
17e00 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72  en.** running pr
17e10 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ior to the sqlit
17e20 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
17e30 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73  all.  ^New SQL s
17e40 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
17e50 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
17e60 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20  ter the running 
17e70 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20  statement count 
17e80 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
17e90 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64  .** not effected
17ea0 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
17eb0 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20  interrupt()..** 
17ec0 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ^A call to sqlit
17ed0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
17ee0 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e  that occurs when
17ef0 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75   there are no ru
17f00 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
17f10 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d  tements is a no-
17f20 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66  op and has no ef
17f30 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74  fect on SQL stat
17f40 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
17f50 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
17f60 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
17f70 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65  errupt() call re
17f80 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  turns..**.** If 
17f90 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
17fa0 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77  nection closes w
17fb0 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e  hile [sqlite3_in
17fc0 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73  terrupt()].** is
17fd0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61   running then ba
17fe0 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69  d things will li
17ff0 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a  kely happen..*/.
18000 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
18010 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
18020 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18030 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
18040 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
18050 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
18060 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
18070 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
18080 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
18090 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
180a0 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
180b0 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
180c0 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
180d0 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
180e0 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
180f0 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
18100 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
18110 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
18120 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
18130 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
18140 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  ng.  ^These rout
18150 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66  ines return 1 if
18160 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
18170 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
18180 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
18190 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41  L statement.  ^A
181a0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
181b0 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
181c0 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
181d0 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
181e0 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
181f0 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20  not a prefix of 
18200 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  a.** well-formed
18210 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
18220 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d  statement.  ^Sem
18230 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
18240 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
18250 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
18260 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
18270 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
18280 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
18290 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
182a0 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
182b0 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
182c0 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
182d0 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
182e0 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
182f0 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
18300 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
18310 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63  tor.  ^Whitespac
18320 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  e.** and comment
18330 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68  s that follow th
18340 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f  e final semicolo
18350 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a  n are ignored..*
18360 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
18370 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66  ines return 0 if
18380 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
18390 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  s incomplete.  ^
183a0 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
183b0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
183c0 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
183d0 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
183e0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
183f0 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
18400 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
18410 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
18420 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
18430 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
18440 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
18450 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73   ^(If SQLite has
18460 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61   not been initia
18470 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  lized using [sql
18480 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
18490 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20  )] prior .** to 
184a0 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  invoking sqlite3
184b0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68  _complete16() th
184c0 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  en sqlite3_initi
184d0 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
184e0 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ed.** automatica
184f0 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63  lly by sqlite3_c
18500 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66  omplete16().  If
18510 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61   that initializa
18520 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74  tion fails,.** t
18530 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
18540 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
18550 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77  3_complete16() w
18560 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a  ill be non-zero.
18570 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
18580 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
18590 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73  the input SQL is
185a0 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a   complete.)^.**.
185b0 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
185c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
185d0 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
185e0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
185f0 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
18600 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
18610 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
18620 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
18630 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
18640 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
18650 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
18660 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e  yte order..*/.in
18670 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
18680 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
18690 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ql);.int sqlite3
186a0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
186b0 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
186c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
186d0 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
186e0 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
186f0 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a  ITE_BUSY Errors.
18700 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
18710 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
18720 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ack function tha
18730 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
18740 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61  ed whenever.** a
18750 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
18760 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61  e to open a data
18770 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20  base table that 
18780 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
18790 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
187a0 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   locked..**.** ^
187b0 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
187c0 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
187d0 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
187e0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
187f0 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73  R_BLOCKED].** is
18800 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
18810 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
18820 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
18830 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
18840 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
18850 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
18860 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
18870 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
18880 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
18890 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
188a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
188b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
188c0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
188d0 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
188e0 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
188f0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
18900 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
18910 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
18920 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
18930 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
18940 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
18950 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
18960 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
18970 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
18980 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f   been invoked fo
18990 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65  r this locking e
189a0 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
189b0 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
189c0 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
189d0 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
189e0 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
189f0 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
18a00 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
18a10 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
18a20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
18a30 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
18a40 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  d..** ^If the ca
18a50 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
18a60 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
18a70 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
18a80 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
18a90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
18aa0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
18ab0 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
18ac0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
18ad0 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
18ae0 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
18af0 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
18b00 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
18b10 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
18b20 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
18b30 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65  n. ^If SQLite de
18b40 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
18b50 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
18b60 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
18b70 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
18b80 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
18b90 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
18ba0 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
18bb0 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
18bc0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e  OERR_BLOCKED] in
18bd0 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
18be0 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  g the busy handl
18bf0 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
18c00 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
18c10 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
18c20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
18c30 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
18c40 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
18c50 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
18c60 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
18c70 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
18c80 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
18c90 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
18ca0 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
18cb0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
18cc0 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
18cd0 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
18ce0 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
18cf0 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
18d00 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
18d10 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
18d20 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
18d30 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
18d40 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
18d50 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
18d60 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
18d70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
18d80 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
18d90 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
18da0 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
18db0 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
18dc0 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
18dd0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
18de0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
18df0 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
18e00 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
18e10 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
18e20 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
18e30 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
18e40 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
18e50 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
18e60 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
18e70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
18e80 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
18e90 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
18ea0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53  ^The [SQLITE_BUS
18eb0 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76  Y] error is conv
18ec0 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45  erted to [SQLITE
18ed0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
18ee0 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
18ef0 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  s in the middle 
18f00 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73  of a large trans
18f10 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c  action where all
18f20 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20   the.** changes 
18f30 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74  will not fit int
18f40 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20  o the in-memory 
18f50 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77  cache.  SQLite w
18f60 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68  ill.** already h
18f70 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c  old a RESERVED l
18f80 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ock on the datab
18f90 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74  ase file, but it
18fa0 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f   needs.** to pro
18fb0 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74  mote this lock t
18fc0 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74  o EXCLUSIVE so t
18fd0 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c  hat it can spill
18fe0 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20   cache.** pages 
18ff0 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
19000 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68  e file without h
19010 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e  arm to concurren
19020 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e  t.** readers.  ^
19030 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  If it is unable 
19040 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c  to promote the l
19050 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e  ock, then the in
19060 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65  -memory.** cache
19070 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e   will be left in
19080 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74   an inconsistent
19090 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68   state and so th
190a0 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
190b0 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d  is promoted from
190c0 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20   the relatively 
190d0 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42  benign [SQLITE_B
190e0 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d  USY] to.** the m
190f0 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49  ore severe [SQLI
19100 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
19110 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20  ].  ^This error 
19120 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a  code promotion.*
19130 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f  * forces an auto
19140 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f  matic rollback o
19150 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20  f the changes.  
19160 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72  See the.** <a hr
19170 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b  ef="/cvstrac/wik
19180 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f  i?p=CorruptionFo
19190 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
191a0 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e  ">.** Corruption
191b0 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
191c0 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65  or</a> wiki page
191d0 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f   for a discussio
191e0 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73  n of why.** this
191f0 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a   is important..*
19200 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
19210 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
19220 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
19230 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
19240 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
19250 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
19260 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
19270 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
19280 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
19290 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
192a0 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
192b0 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
192c0 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69  timeout()].** wi
192d0 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
192e0 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61  lear the busy ha
192f0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
19300 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
19310 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
19320 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
19330 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
19340 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19350 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
19360 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
19370 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
19380 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
19390 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
193a0 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
193b0 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
193c0 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
193d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
193e0 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
193f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
19400 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
19410 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69  sy handler..*/.i
19420 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
19430 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
19440 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  , int(*)(void*,i
19450 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  nt), void*);../*
19460 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
19470 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
19480 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
19490 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
194a0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
194b0 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
194c0 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
194d0 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
194e0 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
194f0 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
19500 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61  locked.  ^The ha
19510 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
19520 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
19530 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
19540 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
19550 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
19560 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
19570 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20  ted.  ^After at 
19580 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
19590 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
195a0 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64  ing,.** the hand
195b0 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
195c0 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69  ich causes [sqli
195d0 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
195e0 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
195f0 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
19600 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
19610 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
19620 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
19630 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
19640 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
19650 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
19660 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
19670 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
19680 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
19690 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
196a0 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20  y handler for a 
196b0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
196c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
196d0 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65  on] any any give
196e0 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e  n moment.  If an
196f0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
19700 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65  er.** was define
19710 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  d  (using [sqlit
19720 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
19730 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
19740 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
19750 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
19760 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
19770 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69   cleared.)^.*/.i
19780 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
19790 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
197a0 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
197b0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
197c0 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
197d0 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
197e0 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ries.**.** This 
197f0 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65  is a legacy inte
19800 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72  rface that is pr
19810 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b  eserved for back
19820 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
19830 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74  ity..** Use of t
19840 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
19850 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64   not recommended
19860 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69  ..**.** Definiti
19870 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20  on: A <b>result 
19880 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d  table</b> is mem
19890 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75  ory data structu
198a0 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68  re created by th
198b0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  e.** [sqlite3_ge
198c0 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72  t_table()] inter
198d0 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20  face.  A result 
198e0 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68  table records th
198f0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75  e.** complete qu
19900 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  ery results from
19910 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65   one or more que
19920 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ries..**.** The 
19930 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c  table conceptual
19940 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20  ly has a number 
19950 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75  of rows and colu
19960 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65  mns.  But.** the
19970 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e  se numbers are n
19980 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72  ot part of the r
19990 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65  esult table itse
199a0 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75  lf.  These.** nu
199b0 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e  mbers are obtain
199c0 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20  ed separately.  
199d0 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d  Let N be the num
199e0 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61  ber of rows.** a
199f0 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62  nd M be the numb
19a00 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  er of columns..*
19a10 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
19a20 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20  ble is an array 
19a30 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  of pointers to z
19a40 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
19a50 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  TF-8 strings..**
19a60 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29   There are (N+1)
19a70 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74  *M elements in t
19a80 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66  he array.  The f
19a90 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20  irst M pointers 
19aa0 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f  point.** to zero
19ab0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
19ac0 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69  ngs that  contai
19ad0 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  n the names of t
19ae0 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54  he columns..** T
19af0 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74  he remaining ent
19b00 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74  ries all point t
19b10 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e  o query results.
19b20 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65    NULL values re
19b30 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20  sult.** in NULL 
19b40 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f  pointers.  All o
19b50 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20  ther values are 
19b60 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a  in their UTF-8 z
19b70 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
19b80 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65  * string represe
19b90 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72  ntation as retur
19ba0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
19bb0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
19bc0 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
19bd0 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69  able might consi
19be0 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  st of one or mor
19bf0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
19c00 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e  ions..** It is n
19c10 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20  ot safe to pass 
19c20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64  a result table d
19c30 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69  irectly to [sqli
19c40 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20  te3_free()]..** 
19c50 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73  A result table s
19c60 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63  hould be dealloc
19c70 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
19c80 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
19c90 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e  ]..**.** ^(As an
19ca0 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
19cb0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
19cc0 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
19cd0 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
19ce0 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
19cf0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
19d00 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
19d10 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
19d20 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
19d30 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
19d40 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
19d50 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
19d60 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
19d70 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
19d80 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
19d90 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
19da0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
19db0 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
19dc0 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
19dd0 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
19de0 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
19df0 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
19e00 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
19e10 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
19e20 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
19e30 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
19e40 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
19e50 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
19e60 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
19e70 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
19e80 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
19e90 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
19ea0 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
19eb0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
19ec0 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
19ed0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
19ee0 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
19ef0 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
19f00 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
19f10 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
19f20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
19f30 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
19f40 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
19f50 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
19f60 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
19f70 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
19f80 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
19f90 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
19fa0 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
19fb0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
19fc0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
19fd0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
19fe0 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
19ff0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
1a000 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
1a010 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
1a020 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
1a030 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
1a040 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
1a050 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
1a060 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  nd returns a res
1a070 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
1a080 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
1a090 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
1a0a0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
1a0b0 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  ter the applicat
1a0c0 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
1a0d0 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74   with the result
1a0e0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65   from sqlite3_ge
1a0f0 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74  t_table(),.** it
1a100 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72   must pass the r
1a110 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
1a120 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
1a130 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
1a140 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
1a150 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
1a160 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
1a170 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
1a180 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
1a190 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
1a1a0 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
1a1b0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1a1c0 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
1a1d0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
1a1e0 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
1a1f0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1a200 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
1a210 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
1a220 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
1a230 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
1a240 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
1a250 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
1a260 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1a270 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
1a280 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
1a290 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
1a2a0 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
1a2b0 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
1a2c0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1a2d0 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
1a2e0 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
1a2f0 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
1a300 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
1a310 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
1a320 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
1a330 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
1a340 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
1a350 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
1a360 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
1a370 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
1a380 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
1a390 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
1a3a0 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
1a3b0 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
1a3c0 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
1a3d0 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
1a3e0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
1a3f0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
1a400 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1a410 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e  errmsg()]..*/.in
1a420 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
1a430 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ble(.  sqlite3 *
1a440 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
1a450 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
1a460 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1a470 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53   *zSql,     /* S
1a480 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
1a490 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a  ed */.  char ***
1a4a0 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a  pazResult,    /*
1a4b0 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   Results of the 
1a4c0 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a  query */.  int *
1a4d0 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20  pnRow,          
1a4e0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
1a4f0 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
1a500 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
1a510 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20  *pnColumn,      
1a520 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1a530 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72  esult columns wr
1a540 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
1a550 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20  char **pzErrmsg 
1a560 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
1a570 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
1a580 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  */.);.void sqlit
1a590 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
1a5a0 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
1a5b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
1a5c0 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
1a5d0 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
1a5e0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
1a5f0 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
1a600 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  -alikes of the "
1a610 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
1a620 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
1a630 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
1a640 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
1a650 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1a660 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
1a670 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
1a680 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
1a690 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
1a6a0 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
1a6b0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
1a6c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
1a6d0 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
1a6e0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1a6f0 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
1a700 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
1a710 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
1a720 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20  free()].  ^Both 
1a730 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1a740 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
1a750 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
1a760 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
1a770 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
1a780 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
1a790 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
1a7a0 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
1a7b0 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
1a7c0 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _snprintf() rout
1a7d0 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
1a7e0 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66  o "snprintf()" f
1a7f0 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
1a800 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20  ard C library.  
1a810 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72  The result is wr
1a820 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a  itten into the.*
1a830 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65  * buffer supplie
1a840 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
1a850 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20  parameter whose 
1a860 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79  size is given by
1a870 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61  .** the first pa
1a880 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68  rameter. Note th
1a890 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20  at the order of 
1a8a0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f  the.** first two
1a8b0 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72   parameters is r
1a8c0 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70  eversed from snp
1a8d0 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73  rintf().)^  This
1a8e0 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
1a8f0 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
1a900 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
1a910 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
1a920 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
1a930 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
1a940 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61   ^(Note also tha
1a950 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
1a960 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
1a970 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
1a980 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
1a990 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
1a9a0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
1a9b0 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
1a9c0 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
1a9d0 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61  )^  We admit tha
1a9e0 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  t.** the number 
1a9f0 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72  of characters wr
1aa00 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61  itten would be a
1aa10 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74   more useful ret
1aa20 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74  urn.** value but
1aa30 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67   we cannot chang
1aa40 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  e the implementa
1aa50 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
1aa60 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f  snprintf().** no
1aa70 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  w without breaki
1aa80 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ng compatibility
1aa90 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67  ..**.** ^As long
1aaa0 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73   as the buffer s
1aab0 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74  ize is greater t
1aac0 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65  han zero, sqlite
1aad0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1aae0 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
1aaf0 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c  the buffer is al
1ab00 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
1ab10 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73  ated.  ^The firs
1ab20 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
1ab30 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
1ab40 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
1ab50 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
1ab60 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
1ab70 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
1ab80 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
1ab90 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
1aba0 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
1abb0 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
1abc0 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
1abd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1abe0 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20  te3_vsnprintf() 
1abf0 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72  routine is a var
1ac00 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20  args version of 
1ac10 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1ac20 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ()..**.** These 
1ac30 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
1ac40 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
1ac50 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
1ac60 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
1ac70 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
1ac80 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
1ac90 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
1aca0 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
1acb0 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
1acc0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
1acd0 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
1ace0 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
1acf0 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
1ad00 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
1ad10 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20  .**.** ^(The %q 
1ad20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1ad30 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
1ad40 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
1ad50 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
1ad60 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20  string from the 
1ad70 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20  argument list.  
1ad80 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62  But %q also doub
1ad90 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63  les every '\'' c
1ada0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20  haracter..** %q 
1adb0 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20  is designed for 
1adc0 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72  use inside a str
1add0 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20  ing literal.)^  
1ade0 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68  By doubling each
1adf0 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74   '\''.** charact
1ae00 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68  er it escapes th
1ae10 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64  at character and
1ae20 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65   allows it to be
1ae30 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a   inserted into.*
1ae40 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a  * the string..**
1ae50 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
1ae60 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69   assume the stri
1ae70 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78  ng variable zTex
1ae80 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20  t contains text 
1ae90 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1aea0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1aeb0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54  re>.**  char *zT
1aec0 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61  ext = "It's a ha
1aed0 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f  ppy day!";.** </
1aee0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1aef0 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20  >.**.** One can 
1af00 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e  use this text in
1af10 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1af20 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
1af30 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1af40 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1af50 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
1af60 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
1af70 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
1af80 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b  ('%q')", zText);
1af90 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
1afa0 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
1afb0 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
1afc0 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
1afd0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1afe0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  ote>.**.** Becau
1aff0 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74  se the %q format
1b000 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c   string is used,
1b010 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63   the '\'' charac
1b020 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20  ter in zText.** 
1b030 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74  is escaped and t
1b040 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64  he SQL generated
1b050 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
1b060 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1b070 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
1b080 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
1b090 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68  ALUES('It''s a h
1b0a0 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c  appy day!').** <
1b0b0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1b0c0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e>.**.** This is
1b0d0 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77   correct.  Had w
1b0e0 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61  e used %s instea
1b0f0 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e  d of %q, the gen
1b100 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f  erated SQL.** wo
1b110 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20  uld have looked 
1b120 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
1b130 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1b140 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
1b150 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
1b160 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64  ('It's a happy d
1b170 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ay!');.** </pre>
1b180 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1b190 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20  .** This second 
1b1a0 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51  example is an SQ
1b1b0 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20  L syntax error. 
1b1c0 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75   As a general ru
1b1d0 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a  le you should.**
1b1e0 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69   always use %q i
1b1f0 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65  nstead of %s whe
1b200 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74  n inserting text
1b210 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c   into a string l
1b220 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  iteral..**.** ^(
1b230 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f  The %Q option wo
1b240 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65  rks like %q exce
1b250 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20  pt it also adds 
1b260 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72  single quotes ar
1b270 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73  ound.** the outs
1b280 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c  ide of the total
1b290 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69   string.  Additi
1b2a0 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70  onally, if the p
1b2b0 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a  arameter in the.
1b2c0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  ** argument list
1b2d0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1b2e0 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74  er, %Q substitut
1b2f0 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c  es the text "NUL
1b300 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73  L" (without.** s
1b310 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e  ingle quotes).)^
1b320 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
1b330 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
1b340 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1b350 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1b360 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
1b370 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
1b380 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
1b390 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
1b3a0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
1b3b0 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
1b3c0 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
1b3d0 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
1b3e0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1b3f0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1b400 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
1b410 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
1b420 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
1b430 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
1b440 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
1b450 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
1b460 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
1b470 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  nter..**.** ^(Th
1b480 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
1b490 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  g option works l
1b4a0 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74  ike "%s" but wit
1b4b0 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f  h the.** additio
1b4c0 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65  n that after the
1b4d0 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e   string has been
1b4e0 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64   read and copied
1b4f0 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73   into.** the res
1b500 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ult, [sqlite3_fr
1b510 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ee()] is called 
1b520 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  on the input str
1b530 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a  ing.)^.*/.char *
1b540 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1b550 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29  const char*,...)
1b560 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
1b570 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  vmprintf(const c
1b580 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1b590 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e  char *sqlite3_sn
1b5a0 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
1b5b0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e  ,const char*, ..
1b5c0 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
1b5d0 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  3_vsnprintf(int,
1b5e0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1b5f0 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a  *, va_list);../*
1b600 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
1b610 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
1b620 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20  Subsystem.**.** 
1b630 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
1b640 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65  uses these three
1b650 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c   routines for al
1b660 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20  l of its own.** 
1b670 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20  internal memory 
1b680 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
1b690 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20  . "Core" in the 
1b6a0 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
1b6b0 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e  e.** does not in
1b6c0 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d  clude operating-
1b6d0 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20  system specific 
1b6e0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
1b6f0 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64  on.  The.** Wind
1b700 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74  ows VFS uses nat
1b710 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  ive malloc() and
1b720 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65   free() for some
1b730 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
1b740 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1b750 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  malloc() routine
1b760 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1b770 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a  er to a block.**
1b780 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65   of memory at le
1b790 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c  ast N bytes in l
1b7a0 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69  ength, where N i
1b7b0 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  s the parameter.
1b7c0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
1b7d0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
1b7e0 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
1b7f0 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
1b800 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
1b810 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
1b820 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61  r.  ^If the para
1b830 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71  meter N to.** sq
1b840 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
1b850 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69  s zero or negati
1b860 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ve then sqlite3_
1b870 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  malloc() returns
1b880 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
1b890 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
1b8a0 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
1b8b0 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
1b8c0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
1b8d0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1b8e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1b8f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1b900 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
1b910 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
1b920 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
1b930 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
1b940 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
1b950 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
1b960 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
1b970 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
1b980 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
1b990 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
1b9a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1b9b0 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
1b9c0 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
1b9d0 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
1b9e0 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
1b9f0 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
1ba00 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
1ba10 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
1ba20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
1ba30 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
1ba40 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
1ba50 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1ba60 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
1ba70 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
1ba80 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
1ba90 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1baa0 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
1bab0 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
1bac0 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
1bad0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
1bae0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
1baf0 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
1bb00 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1bb10 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1bb20 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1bb30 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
1bb40 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65  3_realloc() inte
1bb50 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
1bb60 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
1bb70 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
1bb80 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c  ation to be at l
1bb90 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68  east N bytes, wh
1bba0 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
1bbb0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1bbc0 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c  .  The memory al
1bbd0 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72  location to be r
1bbe0 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69  esized is the fi
1bbf0 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
1bc00 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72  .)^ ^ If the fir
1bc10 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
1bc20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1bc30 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  ).** is a NULL p
1bc40 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20  ointer then its 
1bc50 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e  behavior is iden
1bc60 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67  tical to calling
1bc70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1bc80 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73  oc(N) where N is
1bc90 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1bca0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1bcb0 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e  _realloc()..** ^
1bcc0 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  If the second pa
1bcd0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1bce0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20  e3_realloc() is 
1bcf0 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
1bd00 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
1bd10 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
1bd20 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
1bd30 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
1bd40 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20  free(P) where P 
1bd50 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
1bd60 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1bd70 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
1bd80 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  ^sqlite3_realloc
1bd90 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
1bda0 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
1bdb0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
1bdc0 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
1bdd0 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
1bde0 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74  LL if sufficient
1bdf0 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61   memory is unava
1be00 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d  ilable..** ^If M
1be10 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
1be20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1be30 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
1be40 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
1be50 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1be60 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
1be70 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
1be80 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
1be90 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1bea0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e  te3_realloc() an
1beb0 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  d the prior allo
1bec0 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e  cation is freed.
1bed0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
1bee0 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
1bef0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  s NULL, then the
1bf00 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1bf10 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65  n.** is not free
1bf20 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  d..**.** ^The me
1bf30 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
1bf40 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1bf50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
1bf60 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c  alloc().** is al
1bf70 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
1bf80 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
1bf90 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20  te boundary, or 
1bfa0 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62  to a.** 4 byte b
1bfb0 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b  oundary if the [
1bfc0 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c  SQLITE_4_BYTE_AL
1bfd0 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f  IGNED_MALLOC] co
1bfe0 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
1bff0 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a  tion is used..**
1c000 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65  .** In SQLite ve
1c010 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20  rsion 3.5.0 and 
1c020 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f  3.5.1, it was po
1c030 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65  ssible to define
1c040 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  .** the SQLITE_O
1c050 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
1c060 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c  ATION which woul
1c070 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  d cause the buil
1c080 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  t-in.** implemen
1c090 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20  tation of these 
1c0a0 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f  routines to be o
1c0b0 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61  mitted.  That ca
1c0c0 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e  pability.** is n
1c0d0 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65  o longer provide
1c0e0 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69  d.  Only built-i
1c0f0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
1c100 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e  ors can be used.
1c110 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20  .**.** Prior to 
1c120 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1c130 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f  .7.10, the Windo
1c140 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  ws OS interface 
1c150 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20  layer called.** 
1c160 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
1c170 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
1c180 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
1c190 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
1c1a0 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
1c1b0 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
1c1c0 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
1c1d0 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
1c1e0 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
1c1f0 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
1c200 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
1c210 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
1c220 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
1c230 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65  cation errors we
1c240 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74  re detected, but
1c250 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65  .** they were re
1c260 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b  ported back as [
1c270 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
1c280 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   or.** [SQLITE_I
1c290 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61  OERR] rather tha
1c2a0 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
1c2b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ..**.** The poin
1c2c0 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ter arguments to
1c2d0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1c2e0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
1c2f0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73  ealloc()].** mus
1c300 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c  t be either NULL
1c310 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72   or else pointer
1c320 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
1c330 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63  a prior.** invoc
1c340 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1c350 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
1c360 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c370 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20  )] that have.** 
1c380 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c  not yet been rel
1c390 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eased..**.** The
1c3a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
1c3b0 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72  t not read or wr
1c3c0 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a  ite any part of.
1c3d0 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  ** a block of me
1c3e0 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61  mory after it ha
1c3f0 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20  s been released 
1c400 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
1c410 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71  3_free()] or [sq
1c420 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1c430 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
1c440 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
1c450 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
1c460 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74  alloc(void*, int
1c470 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1c480 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  free(void*);../*
1c490 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
1c4a0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
1c4b0 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  tatistics.**.** 
1c4c0 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20  SQLite provides 
1c4d0 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66  these two interf
1c4e0 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69  aces for reporti
1c4f0 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73  ng on the status
1c500 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
1c510 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
1c520 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c  sqlite3_free()],
1c530 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1c540 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74  alloc()].** rout
1c550 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d  ines, which form
1c560 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65   the built-in me
1c570 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1c580 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  subsystem..**.**
1c590 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1c5a0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
1c5b0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1c5c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1c5d0 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63  s.** of memory c
1c5e0 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
1c5f0 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62  ding (malloced b
1c600 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
1c610 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
1c620 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1c630 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
1c640 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
1c650 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  ** value of [sql
1c660 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1c670 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69  ()] since the hi
1c680 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1c690 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e   was last reset.
1c6a0 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65    ^The values re
1c6b0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1c6c0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1c6d0 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1c6e0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1c6f0 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e  er()] include an
1c700 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64  y overhead.** ad
1c710 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e  ded by SQLite in
1c720 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   its implementat
1c730 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1c740 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75  malloc()],.** bu
1c750 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
1c760 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
1c770 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
1c780 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75  m library.** rou
1c790 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
1c7a0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
1c7b0 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y call..**.** ^T
1c7c0 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77  he memory high-w
1c7d0 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
1c7e0 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
1c7f0 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73  t value of.** [s
1c800 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1c810 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
1c820 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
1c830 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
1c840 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1c850 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20  er()] is true.  
1c860 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
1c870 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  ned.** by [sqlit
1c880 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1c890 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
1c8a0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
1c8b0 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72  * prior to the r
1c8c0 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  eset..*/.sqlite3
1c8d0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
1c8e0 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
1c8f0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
1c900 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1c910 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73  ighwater(int res
1c920 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  etFlag);../*.** 
1c930 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f  CAPI3REF: Pseudo
1c940 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47  -Random Number G
1c950 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53  enerator.**.** S
1c960 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61  QLite contains a
1c970 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73   high-quality ps
1c980 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62  eudo-random numb
1c990 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52  er generator (PR
1c9a0 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73  NG) used to.** s
1c9b0 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f  elect random [RO
1c9c0 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68  WID | ROWIDs] wh
1c9d0 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77  en inserting new
1c9e0 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20   records into a 
1c9f0 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c  table that.** al
1ca00 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c  ready uses the l
1ca10 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20  argest possible 
1ca20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52  [ROWID].  The PR
1ca30 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  NG is also used 
1ca40 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64  for.** the build
1ca50 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64  -in random() and
1ca60 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51   randomblob() SQ
1ca70 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68  L functions.  Th
1ca80 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
1ca90 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ows.** applicati
1caa0 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  ons to access th
1cab0 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20  e same PRNG for 
1cac0 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a  other purposes..
1cad0 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  **.** ^A call to
1cae0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   this routine st
1caf0 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20  ores N bytes of 
1cb00 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
1cb10 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20  buffer P..**.** 
1cb20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
1cb30 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
1cb40 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20  invoked (either 
1cb50 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79  internally or by
1cb60 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
1cb70 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73  ion) the PRNG is
1cb80 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61   seeded using ra
1cb90 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
1cba0 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52  d.** from the xR
1cbb0 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64  andomness method
1cbc0 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
1cbd0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1cbe0 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c  ject..** ^On all
1cbf0 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
1cc00 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65  cations, the pse
1cc10 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69  udo-randomness i
1cc20 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69  s generated.** i
1cc30 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69  nternally and wi
1cc40 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74  thout recourse t
1cc50 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
1cc60 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a  fs] xRandomness.
1cc70 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f  ** method..*/.vo
1cc80 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  id sqlite3_rando
1cc90 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69  mness(int N, voi
1cca0 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d *P);../*.** CA
1ccb0 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
1ccc0 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69  Time Authorizati
1ccd0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
1cce0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1ccf0 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75   registers an au
1cd00 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1cd10 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
1cd20 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
1cd30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
1cd40 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
1cd50 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
1cd60 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
1cd70 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1cd80 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
1cd90 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
1cda0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
1cdb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1cdc0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1cdd0 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
1cde0 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
1cdf0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1ce00 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
1ce10 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1ce20 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a  ].  ^At various.
1ce30 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
1ce40 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
1ce50 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
1ce60 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
1ce70 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
1ce80 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
1ce90 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
1cea0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
1ceb0 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
1cec0 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
1ced0 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e   are allowed.  ^
1cee0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1cef0 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a  allback should.*
1cf00 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
1cf10 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68  _OK] to allow th
1cf20 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54  e action, [SQLIT
1cf30 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73  E_IGNORE] to dis
1cf40 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65  allow the.** spe
1cf50 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74  cific action but
1cf60 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73   allow the SQL s
1cf70 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74  tatement to cont
1cf80 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  inue to be.** co
1cf90 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49  mpiled, or [SQLI
1cfa0 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73  TE_DENY] to caus
1cfb0 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  e the entire SQL
1cfc0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
1cfd0 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74  .** rejected wit
1cfe0 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66  h an error.  ^If
1cff0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1d000 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1d010 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  .** any value ot
1d020 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1d030 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
1d040 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
1d050 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20  E_DENY].** then 
1d060 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
1d070 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
1d080 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
1d090 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20  at triggered.** 
1d0a0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77  the authorizer w
1d0b0 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
1d0c0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
1d0d0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
1d0e0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1d0f0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61  [SQLITE_OK], tha
1d100 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72  t means the oper
1d110 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74  ation.** request
1d120 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e  ed is ok.  ^When
1d130 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1d140 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
1d150 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  NY], the.** [sql
1d160 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1d170 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
1d180 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
1d190 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68  ered the.** auth
1d1a0 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
1d1b0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
1d1c0 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e  essage explainin
1d1d0 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73  g that.** access
1d1e0 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a   is denied. .**.
1d1f0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
1d200 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
1d210 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1d220 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
1d230 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
1d240 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
1d250 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1d260 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
1d270 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
1d280 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
1d290 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
1d2a0 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45   integer [SQLITE
1d2b0 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
1d2c0 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
1d2d0 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69  ies.** the parti
1d2e0 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20  cular action to 
1d2f0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e  be authorized. ^
1d300 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
1d310 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
1d320 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
1d330 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
1d340 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
1d350 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
1d360 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
1d370 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
1d380 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
1d390 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  orized..**.** ^I
1d3a0 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
1d3b0 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
1d3c0 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
1d3d0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1d3e0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
1d3f0 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
1d400 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1d410 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
1d420 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
1d430 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
1d440 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
1d450 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
1d460 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
1d470 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
1d480 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
1d490 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
1d4a0 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
1d4b0 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
1d4c0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
1d4d0 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
1d4e0 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
1d4f0 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
1d500 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
1d510 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  le..** ^If the a
1d520 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
1d530 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e  QLITE_DELETE] an
1d540 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
1d550 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
1d560 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
1d570 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72  he [DELETE] oper
1d580 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62  ation proceeds b
1d590 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63  ut the.** [trunc
1d5a0 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
1d5b0 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e  ] is disabled an
1d5c0 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64  d all rows are d
1d5d0 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61  eleted individua
1d5e0 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  lly..**.** An au
1d5f0 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
1d600 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
1d610 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
1d620 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
1d630 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
1d640 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
1d650 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
1d660 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1d670 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
1d680 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
1d690 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
1d6a0 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
1d6b0 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
1d6c0 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
1d6d0 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
1d6e0 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
1d6f0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
1d700 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
1d710 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
1d720 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
1d730 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
1d740 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
1d750 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
1d760 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
1d770 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
1d780 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
1d790 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
1d7a0 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
1d7b0 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
1d7c0 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
1d7d0 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
1d7e0 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
1d7f0 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
1d800 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
1d810 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
1d820 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
1d830 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
1d840 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
1d850 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
1d860 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
1d870 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
1d880 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
1d890 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
1d8a0 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
1d8b0 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
1d8c0 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
1d8d0 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
1d8e0 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
1d8f0 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
1d900 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
1d910 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
1d920 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
1d930 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
1d940 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
1d950 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
1d960 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
1d970 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c  zer..**.** ^(Onl
1d980 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
1d990 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
1d9a0 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
1d9b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1d9c0 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
1d9d0 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
1d9e0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1d9f0 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
1da00 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
1da10 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68  .)^  ^Disable th
1da20 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
1da30 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
1da40 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
1da50 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
1da60 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
1da70 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
1da80 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1da90 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
1daa0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
1dab0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
1dac0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1dad0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1dae0 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
1daf0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
1db00 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
1db10 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
1db20 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
1db30 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
1db40 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
1db50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
1db60 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
1db70 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
1db80 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
1db90 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65  ** ^When [sqlite
1dba0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1dbb0 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
1dbc0 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
1dbd0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
1dbe0 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65   might be re-pre
1dbf0 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
1dc00 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
1dc10 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
1dc20 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
1dc30 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
1dc40 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
1dc50 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
1dc60 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
1dc70 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
1dc80 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
1dc90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
1dca0 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  p()]..**.** ^Not
1dcb0 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
1dcc0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1dcd0 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
1dce0 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  uring.** [sqlite
1dcf0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
1dd00 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
1dd10 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
1dd20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
1dd30 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
1dd40 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
1dd50 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1dd60 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73  , unless.** as s
1dd70 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65  tated in the pre
1dd80 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c  vious paragraph,
1dd90 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
1dda0 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74  invokes.** sqlit
1ddb0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
1ddc0 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73  to reprepare a s
1ddd0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61  tatement after a
1dde0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a   schema change..
1ddf0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
1de00 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
1de10 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
1de20 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
1de30 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
1de40 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1de50 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1de60 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
1de70 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
1de80 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
1de90 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
1dea0 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
1deb0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1dec0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
1ded0 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
1dee0 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
1def0 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
1df00 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
1df10 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
1df20 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
1df30 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
1df40 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
1df50 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
1df60 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
1df70 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1df80 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
1df90 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
1dfa0 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
1dfb0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
1dfc0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
1dfd0 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45  Note that SQLITE
1dfe0 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20  _IGNORE is also 
1dff0 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54  used as a [SQLIT
1e000 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74  E_ROLLBACK | ret
1e010 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f  urn code].** fro
1e020 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
1e030 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
1e040 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f  )] interface..*/
1e050 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e060 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62  DENY   1   /* Ab
1e070 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  ort the SQL stat
1e080 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72  ement with an er
1e090 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
1e0a0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20  QLITE_IGNORE 2  
1e0b0 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20   /* Don't allow 
1e0c0 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27  access, but don'
1e0d0 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72  t generate an er
1e0e0 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ror */../*.** CA
1e0f0 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
1e100 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a  er Action Codes.
1e110 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
1e120 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1e130 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  r()] interface r
1e140 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
1e150 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
1e160 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
1e170 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72  to authorize cer
1e180 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  tain SQL stateme
1e190 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65  nt actions.  The
1e1a0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
1e1b0 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
1e1c0 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
1e1d0 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65  er code that spe
1e1e0 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61  cifies.** what a
1e1f0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61  ction is being a
1e200 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73  uthorized.  Thes
1e210 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65  e are the intege
1e220 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74  r action codes t
1e230 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  hat.** the autho
1e240 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
1e250 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a  ay be passed..**
1e260 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e  .** These action
1e270 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67   code values sig
1e280 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f  nify what kind o
1e290 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74  f operation is t
1e2a0 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a  o be.** authoriz
1e2b0 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64  ed.  The 3rd and
1e2c0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20   4th parameters 
1e2d0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  to the authoriza
1e2e0 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
1e2f0 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62   function will b
1e300 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
1e310 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
1e320 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65  n which of these
1e330 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65  .** codes is use
1e340 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
1e350 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68  parameter.  ^(Th
1e360 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
1e370 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  to the.** author
1e380 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1e390 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1e3a0 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e   database ("main
1e3b0 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74  ", "temp",.** et
1e3c0 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
1e3d0 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70  e.)^  ^The 6th p
1e3e0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1e3f0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1e400 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ack.** is the na
1e410 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d  me of the inner-
1e420 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
1e430 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
1e440 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
1e450 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
1e460 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
1e470 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
1e480 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
1e490 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  om.** top-level 
1e4a0 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a  SQL code..*/./**
1e4b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e4c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e4d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a  ********* 3rd **
1e4e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a  ********** 4th *
1e4f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66  **********/.#def
1e500 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1e510 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  E_INDEX         
1e520 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   1   /* Index Na
1e530 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1e540 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1e550 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1e560 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
1e570 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  2   /* Table Nam
1e580 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1e590 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1e5a0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1e5b0 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33  TEMP_INDEX     3
1e5c0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1e5d0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1e5e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1e5f0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1e600 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20  EMP_TABLE     4 
1e610 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1e620 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1e630 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e640 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1e650 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20  MP_TRIGGER   5  
1e660 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1e670 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1e680 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e690 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1e6a0 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20  P_VIEW      6   
1e6b0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1e6c0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1e6d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e6e0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47  LITE_CREATE_TRIG
1e6f0 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f  GER        7   /
1e700 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1e710 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1e720 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e730 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20  ITE_CREATE_VIEW 
1e740 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a            8   /*
1e750 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1e760 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1e770 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e780 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  TE_DELETE       
1e790 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20           9   /* 
1e7a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1e7b0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1e7c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e7d0 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20  E_DROP_INDEX    
1e7e0 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49         10   /* I
1e7f0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1e800 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1e810 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e820 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20  _DROP_TABLE     
1e830 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61        11   /* Ta
1e840 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1e850 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1e860 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e870 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20  DROP_TEMP_INDEX 
1e880 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64       12   /* Ind
1e890 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1e8a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1e8b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1e8c0 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ROP_TEMP_TABLE  
1e8d0 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c      13   /* Tabl
1e8e0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1e8f0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1e900 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1e910 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  OP_TEMP_TRIGGER 
1e920 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67     14   /* Trigg
1e930 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1e940 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1e950 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1e960 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  P_TEMP_VIEW     
1e970 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e    15   /* View N
1e980 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1e990 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1e9a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1e9b0 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
1e9c0 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72   16   /* Trigger
1e9d0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1e9e0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1e9f0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1ea00 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20  VIEW            
1ea10 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  17   /* View Nam
1ea20 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1ea30 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1ea40 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  ne SQLITE_INSERT
1ea50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
1ea60 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
1ea70 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1ea80 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1ea90 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20  e SQLITE_PRAGMA 
1eaa0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
1eab0 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d     /* Pragma Nam
1eac0 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72  e     1st arg or
1ead0 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65   NULL */.#define
1eae0 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20   SQLITE_READ    
1eaf0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20               20 
1eb00 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1eb10 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
1eb20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1eb30 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20  SQLITE_SELECT   
1eb40 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20              21  
1eb50 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
1eb60 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1eb70 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1eb80 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f  QLITE_TRANSACTIO
1eb90 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20  N          22   
1eba0 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
1ebb0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1ebc0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ebd0 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20  LITE_UPDATE     
1ebe0 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f            23   /
1ebf0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1ec00 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
1ec10 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ec20 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20  ITE_ATTACH      
1ec30 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a           24   /*
1ec40 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20   Filename       
1ec50 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1ec60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ec70 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20  TE_DETACH       
1ec80 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20          25   /* 
1ec90 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
1eca0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1ecb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ecc0 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20  E_ALTER_TABLE   
1ecd0 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44         26   /* D
1ece0 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54  atabase Name   T
1ecf0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1ed00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ed10 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20  _REINDEX        
1ed20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e        27   /* In
1ed30 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  dex Name      NU
1ed40 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1ed50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ed60 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20  ANALYZE         
1ed70 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62       28   /* Tab
1ed80 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1ed90 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1eda0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1edb0 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20  REATE_VTABLE    
1edc0 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c      29   /* Tabl
1edd0 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
1ede0 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
1edf0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1ee00 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  OP_VTABLE       
1ee10 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65     30   /* Table
1ee20 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
1ee30 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
1ee40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e  efine SQLITE_FUN
1ee50 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20  CTION           
1ee60 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    31   /* NULL  
1ee70 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69            Functi
1ee80 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65  on Name   */.#de
1ee90 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45  fine SQLITE_SAVE
1eea0 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  POINT           
1eeb0 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   32   /* Operati
1eec0 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69  on       Savepoi
1eed0 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66  nt Name  */.#def
1eee0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20  ine SQLITE_COPY 
1eef0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1ef00 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65   0   /* No longe
1ef10 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  r used */../*.**
1ef20 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
1ef30 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
1ef40 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
1ef50 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1ef60 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
1ef70 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  k functions that
1ef80 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72   can be used for
1ef90 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20  .** tracing and 
1efa0 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78  profiling the ex
1efb0 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73  ecution of SQL s
1efc0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
1efd0 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
1efe0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
1eff0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72  ed by sqlite3_tr
1f000 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ace() is invoked
1f010 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74   at.** various t
1f020 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c  imes when an SQL
1f030 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65   statement is be
1f040 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69  ing run by [sqli
1f050 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
1f060 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61  ^The sqlite3_tra
1f070 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ce() callback is
1f080 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20   invoked with a 
1f090 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20  UTF-8 rendering 
1f0a0 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74  of the.** SQL st
1f0b0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20  atement text as 
1f0c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
1f0d0 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75  rst begins execu
1f0e0 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74  ting..** ^(Addit
1f0f0 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72  ional sqlite3_tr
1f100 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20  ace() callbacks 
1f110 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61  might occur.** a
1f120 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64  s each triggered
1f130 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65   subprogram is e
1f140 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c  ntered.  The cal
1f150 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67  lbacks for trigg
1f160 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61  ers.** contain a
1f170 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65   UTF-8 SQL comme
1f180 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69  nt that identifi
1f190 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29  es the trigger.)
1f1a0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ^.**.** The [SQL
1f1b0 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c  ITE_TRACE_SIZE_L
1f1c0 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  IMIT] compile-ti
1f1d0 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  me option can be
1f1e0 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a   used to limit.*
1f1f0 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  * the length of 
1f200 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  [bound parameter
1f210 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74  ] expansion in t
1f220 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c  he output of sql
1f230 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a  ite3_trace()..**
1f240 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
1f250 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
1f260 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
1f270 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
1f280 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
1f290 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
1f2a0 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70  inishes.  ^The p
1f2b0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
1f2c0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
1f2d0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
1f2e0 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65  nt text and an e
1f2f0 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d  stimate of wall-
1f300 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66  clock time.** of
1f310 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73   how long that s
1f320 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
1f330 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66   run.  ^The prof
1f340 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ile callback.** 
1f350 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73  time is in units
1f360 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c   of nanoseconds,
1f370 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72   however the cur
1f380 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
1f390 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63  ion.** is only c
1f3a0 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73  apable of millis
1f3b0 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e  econd resolution
1f3c0 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73   so the six leas
1f3d0 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a  t significant.**
1f3e0 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74   digits in the t
1f3f0 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c  ime are meaningl
1f400 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72  ess.  Future ver
1f410 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a  sions of SQLite.
1f420 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65  ** might provide
1f430 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74   greater resolut
1f440 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69  ion on the profi
1f450 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54  ler callback.  T
1f460 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  he.** sqlite3_pr
1f470 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  ofile() function
1f480 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65   is considered e
1f490 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
1f4a0 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f  is.** subject to
1f4b0 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
1f4c0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
1f4d0 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  Lite..*/.void *s
1f4e0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
1f4f0 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72  ite3*, void(*xTr
1f500 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
1f510 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
1f520 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
1f530 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74  NTAL void *sqlit
1f540 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
1f550 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
1f560 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
1f570 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
1f580 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
1f590 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1f5a0 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
1f5b0 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  ss Callbacks.**.
1f5c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1f5d0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
1f5e0 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66  (D,N,X,P) interf
1f5f0 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63  ace causes the c
1f600 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
1f610 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f  ion X to be invo
1f620 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
1f630 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e   during long run
1f640 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ning calls to.**
1f650 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1f660 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
1f670 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1f680 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f  _get_table()] fo
1f690 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
1f6a0 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20  nnection D.  An 
1f6b0 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
1f6c0 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
1f6d0 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
1f6e0 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
1f6f0 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
1f700 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61  .**.** ^The para
1f710 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65  meter P is passe
1f720 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
1f730 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
1f740 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62  to the .** callb
1f750 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20  ack function X. 
1f760 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
1f770 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69  N is the approxi
1f780 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a  mate number of .
1f790 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68  ** [virtual mach
1f7a0 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73  ine instructions
1f7b0 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75  ] that are evalu
1f7c0 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63  ated between suc
1f7d0 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63  cessive.** invoc
1f7e0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61  ations of the ca
1f7f0 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e  llback X.  ^If N
1f800 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e   is less than on
1f810 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72  e then the progr
1f820 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69  ess.** handler i
1f830 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  s disabled..**.*
1f840 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  * ^Only a single
1f850 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1f860 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64  r may be defined
1f870 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72   at one time per
1f880 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1f890 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69  nnection]; setti
1f8a0 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73  ng a new progres
1f8b0 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c  s handler cancel
1f8c0 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65  s the.** old one
1f8d0 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61  .  ^Setting para
1f8e0 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20  meter X to NULL 
1f8f0 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f  disables the pro
1f900 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
1f910 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20  * ^The progress 
1f920 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20  handler is also 
1f930 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74  disabled by sett
1f940 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65  ing N to a value
1f950 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e   less.** than 1.
1f960 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  .**.** ^If the p
1f970 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
1f980 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
1f990 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  o, the operation
1f9a0 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74   is.** interrupt
1f9b0 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72  ed.  This featur
1f9c0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
1f9d0 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20   implement a.** 
1f9e0 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
1f9f0 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73  on a GUI progres
1fa00 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a  s dialog box..**
1fa10 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73  .** The progress
1fa20 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
1fa30 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
1fa40 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1fa50 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1fa60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1fa70 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1fa80 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
1fa90 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
1faa0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
1fab0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
1fac0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
1fad0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
1fae0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1faf0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
1fb00 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
1fb10 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
1fb20 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f  agraph..**.*/.vo
1fb30 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
1fb40 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
1fb50 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
1fb60 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
1fb70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1fb80 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
1fb90 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
1fba0 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  tion.**.** ^Thes
1fbb0 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
1fbc0 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
1fbd0 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69  se file as speci
1fbe0 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
1fbf0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1fc00 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  t. ^The filename
1fc10 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
1fc20 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
1fc30 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
1fc40 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
1fc50 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
1fc60 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
1fc70 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
1fc80 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
1fc90 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28  te3_open16(). ^(
1fca0 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
1fcb0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
1fcc0 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
1fcd0 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
1fce0 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
1fcf0 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
1fd00 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
1fd10 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
1fd20 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
1fd30 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
1fd40 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
1fd50 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
1fd60 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
1fd70 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
1fd80 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
1fd90 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
1fda0 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
1fdb0 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61  t.)^ ^(If the da
1fdc0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1fdd0 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
1fde0 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
1fdf0 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
1fe00 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
1fe10 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
1fe20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
1fe30 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a  eturned.)^ ^The.
1fe40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
1fe50 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
1fe60 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
1fe70 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
1fe80 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
1fe90 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
1fea0 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
1feb0 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c  of the error fol
1fec0 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65  lowing a failure
1fed0 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
1fee0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
1fef0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
1ff00 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
1ff10 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64  coding for the d
1ff20 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
1ff30 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69  UTF-8 if.** sqli
1ff40 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
1ff50 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1ff60 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a  is called and.**
1ff70 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
1ff80 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1ff90 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   if sqlite3_open
1ffa0 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a  16() is used..**
1ffb0 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
1ffc0 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
1ffd0 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
1ffe0 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
1fff0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
20000 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
20010 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
20020 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
20030 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
20040 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
20050 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
20060 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
20070 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
20080 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
20090 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
200a0 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
200b0 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
200c0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
200d0 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
200e0 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
200f0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
20100 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
20110 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
20120 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
20130 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
20140 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
20150 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
20160 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
20170 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
20180 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
20190 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
201a0 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
201b0 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
201c0 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
201d0 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
201e0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
201f0 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  CHE],.** [SQLITE
20200 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
20210 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  HE], and/or [SQL
20220 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
20230 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
20240 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
20250 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
20260 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
20270 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
20280 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
20290 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
202a0 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
202b0 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
202c0 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
202d0 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
202e0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
202f0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
20300 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
20310 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
20320 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
20330 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
20340 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
20350 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
20360 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
20370 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
20380 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
20390 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
203a0 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
203b0 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
203c0 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
203d0 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
203e0 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
203f0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
20400 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
20410 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
20420 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
20430 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
20440 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
20450 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
20460 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
20470 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69   created if.** i
20480 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
20490 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
204a0 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
204b0 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
204c0 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
204d0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
204e0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
204f0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
20500 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
20510 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
20520 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
20530 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
20540 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
20550 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74   shown above opt
20560 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
20570 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b   with other.** [
20580 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
20590 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50  ONLY | SQLITE_OP
205a0 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68  EN_* bits].** th
205b0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
205c0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
205d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
205e0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
205f0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
20600 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
20610 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
20620 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74  pens in the mult
20630 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
20640 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e  ing mode] as lon
20650 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d  g as the single-
20660 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68  thread.** mode h
20670 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20  as not been set 
20680 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
20690 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20  or start-time.  
206a0 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
206b0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
206c0 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
206d0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
206e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
206f0 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
20700 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
20710 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
20720 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
20730 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
20740 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
20750 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
20760 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b  -time..** ^The [
20770 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
20780 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  EDCACHE] flag ca
20790 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
207a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
207b0 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74  be.** eligible t
207c0 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61  o use [shared ca
207d0 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72  che mode], regar
207e0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
207f0 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a   or not shared.*
20800 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
20810 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
20820 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
20830 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a  cache()].  ^The.
20840 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
20850 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
20860 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
20870 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20880 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74  n to not.** part
20890 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72  icipate in [shar
208a0 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65  ed cache mode] e
208b0 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61  ven if it is ena
208c0 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
208d0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
208e0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
208f0 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
20900 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
20910 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
20920 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
20930 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
20940 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
20950 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
20960 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20970 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e  n should use.  ^
20980 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
20990 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20  rameter is.** a 
209a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
209b0 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  n the default [s
209c0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
209d0 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
209e0 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
209f0 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
20a00 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
20a10 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
20a20 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
20a30 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
20a40 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
20a50 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
20a60 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
20a70 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
20a80 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
20a90 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
20aa0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
20ab0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
20ac0 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
20ad0 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
20ae0 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
20af0 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
20b00 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
20b10 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
20b20 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
20b30 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
20b40 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
20b50 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
20b60 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
20b70 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
20b80 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
20b90 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
20ba0 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
20bb0 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
20bc0 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
20bd0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
20be0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
20bf0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
20c00 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
20c10 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
20c20 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
20c30 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
20c40 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
20c50 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
20c60 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
20c70 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
20c80 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
20c90 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  sed..**.** [[URI
20ca0 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71   filenames in sq
20cb0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c  lite3_open()]] <
20cc0 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73  h3>URI Filenames
20cd0 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  </h3>.**.** ^If 
20ce0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69  [URI filename] i
20cf0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
20d00 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68   enabled, and th
20d10 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
20d20 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69  ent.** begins wi
20d30 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e  th "file:", then
20d40 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
20d50 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
20d60 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66  a URI. ^URI.** f
20d70 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
20d80 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
20d90 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  d if the [SQLITE
20da0 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
20db0 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65  is.** set in the
20dc0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
20dd0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
20de0 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20  _v2(), or if it 
20df0 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62  has.** been enab
20e00 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69  led globally usi
20e10 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
20e20 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f  ONFIG_URI] optio
20e30 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73  n with the.** [s
20e40 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
20e50 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68   method or by th
20e60 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  e [SQLITE_USE_UR
20e70 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  I] compile-time 
20e80 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66  option..** As of
20e90 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
20ea0 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e  3.7.7, URI filen
20eb0 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
20ec0 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66  on is turned off
20ed0 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20  .** by default, 
20ee0 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61  but future relea
20ef0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ses of SQLite mi
20f00 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66  ght enable URI f
20f10 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72  ilename.** inter
20f20 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66  pretation by def
20f30 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49  ault.  See "[URI
20f40 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72   filenames]" for
20f50 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
20f60 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
20f70 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  * URI filenames 
20f80 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72  are parsed accor
20f90 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36  ding to RFC 3986
20fa0 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f  . ^If the URI co
20fb0 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74  ntains an.** aut
20fc0 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20  hority, then it 
20fd0 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
20fe0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
20ff0 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a  r the string .**
21000 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49   "localhost". ^I
21010 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  f the authority 
21020 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20  is not an empty 
21030 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c  string or "local
21040 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72  host", an .** er
21050 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
21060 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e  to the caller. ^
21070 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d  The fragment com
21080 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c  ponent of a URI,
21090 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c   if .** present,
210a0 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
210b0 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
210c0 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65  the path compone
210d0 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73  nt of the URI as
210e0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
210f0 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68   disk file.** wh
21100 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ich contains the
21110 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74   database. ^If t
21120 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77  he path begins w
21130 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63  ith a '/' charac
21140 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74  ter, .** then it
21150 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
21160 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  as an absolute p
21170 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ath. ^If the pat
21180 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e  h does not begin
21190 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20   .** with a '/' 
211a0 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68  (meaning that th
211b0 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74  e authority sect
211c0 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66  ion is omitted f
211d0 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20  rom the URI).** 
211e0 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73  then the path is
211f0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
21200 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e  a relative path.
21210 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73   .** ^On windows
21220 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70  , the first comp
21230 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f  onent of an abso
21240 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73  lute path .** is
21250 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69   a drive specifi
21260 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a  cation (e.g. "C:
21270 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65  ")..**.** [[core
21280 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d   URI query param
21290 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71  eters]].** The q
212a0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
212b0 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74  f a URI may cont
212c0 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ain parameters t
212d0 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65  hat are interpre
212e0 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79  ted.** either by
212f0 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20   SQLite itself, 
21300 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63  or by a [VFS | c
21310 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d  ustom VFS implem
21320 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51  entation]..** SQ
21330 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
21340 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
21350 72 65 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  ree query parame
21360 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ters:.**.** <ul>
21370 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66  .**   <li> <b>vf
21380 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73  s</b>: ^The "vfs
21390 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  " parameter may 
213a0 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69  be used to speci
213b0 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a  fy the name of.*
213c0 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65  *     a VFS obje
213d0 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73  ct that provides
213e0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
213f0 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
21400 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20  that should.**  
21410 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63     be used to ac
21420 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
21430 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20  e file on disk. 
21440 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ^If this option 
21450 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20  is set to.**    
21460 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
21470 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
21480 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
21490 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
214a0 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56  unknown.**     V
214b0 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20  FS is an error. 
214c0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
214d0 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
214e0 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e  d the vfs option
214f0 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65   is.**     prese
21500 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53  nt, then the VFS
21510 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
21520 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70  e option takes p
21530 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a  recedence over.*
21540 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20  *     the value 
21550 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f  passed as the fo
21560 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
21570 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
21580 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
21590 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e  > <b>mode</b>: ^
215a0 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65  (The mode parame
215b0 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
215c0 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22  o either "ro", "
215d0 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63  rw",.**     "rwc
215e0 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20  ", or "memory". 
215f0 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65  Attempting to se
21600 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65  t it to any othe
21610 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20  r value is.**   
21620 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a    an error)^. .*
21630 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69  *     ^If "ro" i
21640 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65  s specified, the
21650 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
21660 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
21670 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61  d-only .**     a
21680 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69  ccess, just as i
21690 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
216a0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61  EN_READONLY] fla
216b0 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69  g had been set i
216c0 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68  n the .**     th
216d0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
216e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
216f0 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  ). ^If the mode 
21700 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
21710 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74   .**     "rw", t
21720 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
21730 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
21740 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e  ead-write (but n
21750 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20  ot create) .**  
21760 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66     access, as if
21770 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
21780 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20  DWRITE (but not 
21790 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
217a0 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20  TE) had .**     
217b0 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65  been set. ^Value
217c0 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61   "rwc" is equiva
217d0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
217e0 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c  both .**     SQL
217f0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
21800 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50  TE and SQLITE_OP
21810 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20  EN_CREATE.  ^If 
21820 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
21830 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f  is.**     set to
21840 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61   "memory" then a
21850 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79   pure [in-memory
21860 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20   database] that 
21870 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20  never reads.**  
21880 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f     or writes fro
21890 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20  m disk is used. 
218a0 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20  ^It is an error 
218b0 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c  to specify a val
218c0 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68  ue for.**     th
218d0 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
218e0 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65   that is less re
218f0 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74  strictive than t
21900 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79  hat specified by
21910 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67  .**     the flag
21920 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20  s passed in the 
21930 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
21940 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
21950 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
21960 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a  i> <b>cache</b>:
21970 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61   ^The cache para
21980 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
21990 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72   to either "shar
219a0 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70  ed" or.**     "p
219b0 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e  rivate". ^Settin
219c0 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22  g it to "shared"
219d0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
219e0 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a  o setting the.**
219f0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
21a00 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74  _SHAREDCACHE bit
21a10 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72   in the flags ar
21a20 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f  gument passed to
21a30 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f  .**     sqlite3_
21a40 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74  open_v2(). ^Sett
21a50 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61  ing the cache pa
21a60 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76  rameter to "priv
21a70 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20  ate" is .**     
21a80 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
21a90 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  tting the SQLITE
21aa0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
21ab0 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e  HE bit..**     ^
21ac0 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
21ad0 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
21ae0 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72   the "cache" par
21af0 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e  ameter is presen
21b00 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52  t in.**     a UR
21b10 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20  I filename, its 
21b20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20  value overrides 
21b30 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71  any behavior req
21b40 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e  uested by settin
21b50 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  g.**     SQLITE_
21b60 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
21b70 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e  E or SQLITE_OPEN
21b80 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61  _SHAREDCACHE fla
21b90 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  g..** </ul>.**.*
21ba0 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  * ^Specifying an
21bb0 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74   unknown paramet
21bc0 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  er in the query 
21bd0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
21be0 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20  RI is not an.** 
21bf0 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76  error.  Future v
21c00 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
21c10 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61  e might understa
21c20 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75  nd additional qu
21c30 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
21c40 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20  s.  See "[query 
21c50 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20  parameters with 
21c60 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20  special meaning 
21c70 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a  to SQLite]" for.
21c80 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
21c90 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
21ca0 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20   [[URI filename 
21cb0 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55  examples]] <h3>U
21cc0 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
21cd0 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ples</h3>.**.** 
21ce0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
21cf0 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63  " align=center c
21d00 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a  ellpadding=5>.**
21d10 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69   <tr><th> URI fi
21d20 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73  lenames <th> Res
21d30 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ults.** <tr><td>
21d40 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74   file:data.db <t
21d50 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
21d60 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
21d70 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
21d80 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
21d90 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
21da0 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
21db0 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20  ta.db<br>.**    
21dc0 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f        file:///ho
21dd0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
21de0 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <br> .**        
21df0 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f    file://localho
21e00 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  st/home/fred/dat
21e10 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a  a.db <br> <td> .
21e20 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
21e30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
21e40 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
21e50 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e  ata.db"..** <tr>
21e60 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b  <td> file://dark
21e70 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  star/home/fred/d
21e80 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
21e90 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
21ea0 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73  r. "darkstar" is
21eb0 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65   not a recognize
21ec0 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20  d authority..** 
21ed0 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77  <tr><td style="w
21ee0 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61  hite-space:nowra
21ef0 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  p"> .**         
21f00 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75   file:///C:/Docu
21f10 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65  ments%20and%20Se
21f20 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b  ttings/fred/Desk
21f30 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20  top/data.db.**  
21f40 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20     <td> Windows 
21f50 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66  only: Open the f
21f60 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e  ile "data.db" on
21f70 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20   fred's desktop 
21f80 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20  on drive.**     
21f90 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68       C:. Note th
21fa0 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70  at the %20 escap
21fb0 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d  ing in this exam
21fc0 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63  ple is not stric
21fd0 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  tly .**         
21fe0 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61   necessary - spa
21ff0 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61  ce characters ca
22000 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61  n be used litera
22010 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lly.**          
22020 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  in URI filenames
22030 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
22040 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
22050 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65  ro&cache=private
22060 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
22070 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61     Open file "da
22080 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
22090 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20  rrent directory 
220a0 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63  for read-only ac
220b0 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20  cess..**        
220c0 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20    Regardless of 
220d0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
220e0 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65  hared-cache mode
220f0 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a   is enabled by.*
22100 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75  *          defau
22110 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74  lt, use a privat
22120 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e  e cache..** <tr>
22130 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
22140 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73  fred/data.db?vfs
22150 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64  =unix-nolock <td
22160 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70  >.**          Op
22170 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  en file "/home/f
22180 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73  red/data.db". Us
22190 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46  e the special VF
221a0 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e  S "unix-nolock".
221b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
221c0 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
221d0 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a  eadonly <td> .**
221e0 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
221f0 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69  or. "readonly" i
22200 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70  s not a valid op
22210 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f  tion for the "mo
22220 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  de" parameter..*
22230 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a  * </table>.**.**
22240 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61   ^URI hexadecima
22250 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
22260 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70  es (%HH) are sup
22270 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68  ported within th
22280 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75  e path and.** qu
22290 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
222a0 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64  f a URI. A hexad
222b0 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
222c0 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20  quence consists 
222d0 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20  of a.** percent 
222e0 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c  sign - "%" - fol
222f0 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79  lowed by exactly
22300 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c   two hexadecimal
22310 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63   digits .** spec
22320 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20  ifying an octet 
22330 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74  value. ^Before t
22340 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79  he path or query
22350 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
22360 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
22370 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
22380 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64  , they are encod
22390 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61  ed using UTF-8 a
223a0 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64  nd all .** hexad
223b0 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
223c0 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64  quences replaced
223d0 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74   by a single byt
223e0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
223f0 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  .** correspondin
22400 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73  g octet. If this
22410 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74   process generat
22420 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54  es an invalid UT
22430 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a  F-8 encoding,.**
22440 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
22450 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
22460 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
22470 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
22480 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
22490 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
224a0 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
224b0 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  of sqlite3_open(
224c0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
224d0 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20  en_v2() must be 
224e0 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65  UTF-8, not whate
224f0 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20  ver.** codepage 
22500 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  is currently def
22510 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73  ined.  Filenames
22520 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65   containing inte
22530 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61  rnational.** cha
22540 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20  racters must be 
22550 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46  converted to UTF
22560 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73  -8 prior to pass
22570 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a  ing them into.**
22580 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
22590 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
225a0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  v2()..**.** <b>N
225b0 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52  ote to Windows R
225c0 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62  untime users:</b
225d0 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79  >  The temporary
225e0 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20   directory must 
225f0 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20  be set.** prior 
22600 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  to calling sqlit
22610 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
22620 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
22630 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69   Otherwise, vari
22640 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20  ous.** features 
22650 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65  that require the
22660 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72   use of temporar
22670 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c  y files may fail
22680 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
22690 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  : [sqlite3_temp_
226a0 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e  directory].*/.in
226b0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
226c0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
226d0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
226e0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
226f0 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
22700 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
22710 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
22720 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
22730 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
22740 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
22750 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
22760 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
22770 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
22780 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
22790 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
227a0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
227b0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
227c0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
227d0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
227e0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
227f0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
22800 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
22810 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
22820 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
22830 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
22840 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
22850 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
22860 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
22870 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
22880 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
22890 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
228a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
228b0 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65  EF: Obtain Value
228c0 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65  s For URI Parame
228d0 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ters.**.** These
228e0 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75   are utility rou
228f0 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f  tines, useful to
22900 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
22910 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b  ions, that check
22920 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20  .** to see if a 
22930 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
22940 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e  s a URI that con
22950 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69  tained a specifi
22960 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61  c query .** para
22970 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f  meter, and if so
22980 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c   obtains the val
22990 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79  ue of that query
229a0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
229b0 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61  * If F is the da
229c0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
229d0 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69  pointer passed i
229e0 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20  nto the xOpen() 
229f0 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20  method of .** a 
22a00 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
22a10 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67  on when the flag
22a20 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  s parameter to x
22a30 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f  Open() has one o
22a40 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68  r .** more of th
22a50 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
22a60 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  RI] or [SQLITE_O
22a70 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74  PEN_MAIN_DB] bit
22a80 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69  s set and.** P i
22a90 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
22aa0 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
22ab0 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  r, then.** sqlit
22ac0 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
22ad0 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68  (F,P) returns th
22ae0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50  e value of the P
22af0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66  .** parameter if
22b00 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20   it exists or a 
22b10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
22b20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61  P does not appea
22b30 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79  r as a .** query
22b40 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e   parameter on F.
22b50 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72    If P is a quer
22b60 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46  y parameter of F
22b70 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69  .** has no expli
22b80 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  cit value, then 
22b90 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
22ba0 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
22bb0 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ns.** a pointer 
22bc0 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
22bd0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ng..**.** The sq
22be0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
22bf0 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
22c00 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20   assumes that P 
22c10 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20  is a boolean.** 
22c20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
22c30 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f  turns true (1) o
22c40 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f  r false (0) acco
22c50 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c  rding to the val
22c60 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65  ue.** of P.  The
22c70 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
22c80 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
22c90 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ine returns true
22ca0 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76   (1) if the.** v
22cb0 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61  alue of query pa
22cc0 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
22cd0 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65   of "yes", "true
22ce0 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e  ", or "on" in an
22cf0 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20  y.** case or if 
22d00 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
22d10 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f   with a non-zero
22d20 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a   number.  The .*
22d30 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
22d40 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
22d50 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61  tines returns fa
22d60 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76  lse (0) if the v
22d70 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79  alue of.** query
22d80 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
22d90 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61  one of "no", "fa
22da0 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69  lse", or "off" i
22db0 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a  n any case or.**
22dc0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
22dd0 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65  gins with a nume
22de0 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20  ric zero.  If P 
22df0 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a  is not a query.*
22e00 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  * parameter on F
22e10 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
22e20 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f   of P is does no
22e30 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74  t match any of t
22e40 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65  he.** above, the
22e50 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  n sqlite3_uri_bo
22e60 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
22e70 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a  urns (B!=0)..**.
22e80 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
22e90 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20  ri_int64(F,P,D) 
22ea0 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73  routine converts
22eb0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
22ec0 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74  into a.** 64-bit
22ed0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
22ee0 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74  and returns that
22ef0 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69   integer, or D i
22f00 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  f P does not.** 
22f10 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76  exist.  If the v
22f20 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d  alue of P is som
22f30 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
22f40 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  n an integer, th
22f50 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65  en.** zero is re
22f60 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49  turned..** .** I
22f70 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f F is a NULL po
22f80 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69  inter, then sqli
22f90 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
22fa0 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e  r(F,P) returns N
22fb0 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  ULL and.** sqlit
22fc0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
22fd0 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e  ,P,B) returns B.
22fe0 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20    If F is not a 
22ff0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
23000 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74  .** is not a dat
23010 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e  abase file pathn
23020 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ame pointer that
23030 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69   SQLite passed i
23040 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a  nto the xOpen.**
23050 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65   VFS method, the
23060 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
23070 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  f this routine i
23080 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
23090 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65  probably.** unde
230a0 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73  sirable..*/.cons
230b0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
230c0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f  uri_parameter(co
230d0 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
230e0 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ame, const char 
230f0 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71  *zParam);.int sq
23100 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
23110 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  n(const char *zF
23120 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ile, const char 
23130 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65  *zParam, int bDe
23140 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f  fault);.sqlite3_
23150 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72  int64 sqlite3_ur
23160 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68  i_int64(const ch
23170 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  ar*, const char*
23180 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
23190 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
231a0 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
231b0 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a  And Messages.**.
231c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
231d0 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66  errcode() interf
231e0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
231f0 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
23200 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
23210 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
23220 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20  e] for the most 
23230 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71  recent failed sq
23240 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
23250 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
23260 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
23270 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20  connection]. If 
23280 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c  a prior API call
23290 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74   failed.** but t
232a0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  he most recent A
232b0 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65  PI call succeede
232c0 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  d, the return va
232d0 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  lue from.** sqli
232e0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
232f0 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   undefined.  ^Th
23300 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
23310 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  ed_errcode().** 
23320 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65  interface is the
23330 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61   same except tha
23340 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  t it always retu
23350 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74  rns the .** [ext
23360 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
23370 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74  e] even when ext
23380 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
23390 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  es are.** disabl
233a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
233b0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
233c0 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
233d0 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
233e0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
233f0 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
23400 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
23410 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
23420 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
23430 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65  ctively..** ^(Me
23440 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
23450 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
23460 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
23470 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
23480 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
23490 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
234a0 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
234b0 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
234c0 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
234d0 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
234e0 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
234f0 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
23500 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
23510 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
23520 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
23530 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a  ce functions.)^.
23540 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
23550 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65  e3_errstr() inte
23560 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
23570 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  e English-langua
23580 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20  ge text.** that 
23590 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72  describes the [r
235a0 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20  esult code], as 
235b0 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  UTF-8..** ^(Memo
235c0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
235d0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
235e0 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
235f0 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64  nternally.** and
23600 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65   must not be fre
23610 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
23620 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57  ation)^..**.** W
23630 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a  hen the serializ
23640 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
23650 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69  de] is in use, i
23660 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a  t might be the.*
23670 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65  * case that a se
23680 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72  cond error occur
23690 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20  s on a separate 
236a0 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65  thread in betwee
236b0 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66  n.** the time of
236c0 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72   the first error
236d0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f   and the call to
236e0 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
236f0 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20  s..** When that 
23700 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63  happens, the sec
23710 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62  ond error will b
23720 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65  e reported since
23730 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66   these.** interf
23740 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f  aces always repo
23750 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  rt the most rece
23760 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61  nt result.  To a
23770 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61  void.** this, ea
23780 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62  ch thread can ob
23790 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75  tain exclusive u
237a0 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  se of the [datab
237b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
237c0 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67  D.** by invoking
237d0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
237e0 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f  enter]([sqlite3_
237f0 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65  db_mutex](D)) be
23800 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a  fore beginning.*
23810 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69  * to use D and i
23820 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
23830 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73  _mutex_leave]([s
23840 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
23850 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c  (D)) after.** al
23860 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69  l calls to the i
23870 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64  nterfaces listed
23880 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65   here are comple
23890 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ted..**.** If an
238a0 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
238b0 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53   with SQLITE_MIS
238c0 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  USE, that means 
238d0 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
238e0 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63   was invoked inc
238f0 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  orrectly by the 
23900 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e  application.  In
23910 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a   that case, the.
23920 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  ** error code an
23930 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72  d message may or
23940 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e   may not be set.
23950 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
23960 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
23970 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *db);.int sqlite
23980 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
23990 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
239a0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
239b0 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
239c0 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  te3*);.const voi
239d0 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
239e0 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  g16(sqlite3*);.c
239f0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
23a00 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a  e3_errstr(int);.
23a10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23a20 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f   SQL Statement O
23a30 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
23a40 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
23a50 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
23a60 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
23a70 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
23a80 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
23a90 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
23aa0 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
23ab0 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
23ac0 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e   is variously kn
23ad0 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72  own as a "prepar
23ae0 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  ed statement" or
23af0 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20   a.** "compiled 
23b00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  SQL statement" o
23b10 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73  r simply as a "s
23b20 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a  tatement"..**.**
23b30 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73   The life of a s
23b40 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
23b50 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c  goes something l
23b60 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
23b70 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
23b80 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75  ate the object u
23b90 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
23ba0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61  epare_v2()] or a
23bb0 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20   related.**     
23bc0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c   function..** <l
23bd0 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
23be0 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  o [host paramete
23bf0 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71  rs] using the sq
23c00 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
23c10 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65  *      interface
23c20 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  s..** <li> Run t
23c30 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
23c40 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
23c50 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
23c60 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
23c70 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  set the statemen
23c80 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
23c90 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
23ca0 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
23cb0 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
23cc0 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
23cd0 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
23ce0 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
23cf0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
23d00 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
23d10 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66   </ol>.**.** Ref
23d20 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74  er to documentat
23d30 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
23d40 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  l methods above 
23d50 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
23d60 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
23d70 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
23d80 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
23d90 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
23da0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
23db0 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a  -time Limits.**.
23dc0 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66  ** ^(This interf
23dd0 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
23de0 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
23df0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
23e00 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
23e10 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
23e20 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
23e30 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
23e40 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
23e50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
23e60 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
23e70 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
23e80 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
23e90 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
23ea0 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
23eb0 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
23ec0 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
23ed0 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
23ee0 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
23ef0 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
23f00 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
23f10 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
23f20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
23f30 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a  onstruct.)^.**.*
23f40 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69  * ^If the new li
23f50 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
23f60 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
23f70 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
23f80 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20  ..** ^(For each 
23f90 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53  limit category S
23fa0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e  QLITE_LIMIT_<i>N
23fb0 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73  AME</i> there is
23fc0 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c   a .** [limits |
23fd0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
23fe0 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d  d].** set at com
23ff0 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43  pile-time by a C
24000 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
24010 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c  cro called.** [l
24020 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d  imits | SQLITE_M
24030 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e  AX_<i>NAME</i>].
24040 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
24050 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
24060 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
24070 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74  AX_".))^.** ^Att
24080 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
24090 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
240a0 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
240b0 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
240c0 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
240d0 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
240e0 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52   bound..**.** ^R
240f0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
24100 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
24110 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65  limit was change
24120 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  d, the .** [sqli
24130 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74  te3_limit()] int
24140 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
24150 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
24160 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20  f the limit..** 
24170 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20  ^Hence, to find 
24180 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
24190 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74  e of a limit wit
241a0 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74  hout changing it
241b0 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f  ,.** simply invo
241c0 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ke this interfac
241d0 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64  e with the third
241e0 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74   parameter set t
241f0 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d  o -1..**.** Run-
24200 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20  time limits are 
24210 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
24220 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   in applications
24230 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20   that manage.** 
24240 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69  both their own i
24250 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
24260 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61   and also databa
24270 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ses that are con
24280 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e  trolled.** by un
24290 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c  trusted external
242a0 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78   sources.  An ex
242b0 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f  ample applicatio
242c0 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20  n might be a.** 
242d0 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74  web browser that
242e0 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74   has its own dat
242f0 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69  abases for stori
24300 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a  ng history and.*
24310 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  * separate datab
24320 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  ases controlled 
24330 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70  by JavaScript ap
24340 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c  plications downl
24350 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65  oaded.** off the
24360 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20   Internet.  The 
24370 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
24380 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20  es can be given 
24390 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65  the.** large, de
243a0 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44  fault limits.  D
243b0 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64  atabases managed
243c0 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75   by external sou
243d0 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67  rces can.** be g
243e0 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65  iven much smalle
243f0 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65  r limits designe
24400 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64  d to prevent a d
24410 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65  enial of service
24420 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76  .** attack.  Dev
24430 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c  elopers might al
24440 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74  so want to use t
24450 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
24460 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a  authorizer()].**
24470 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75   interface to fu
24480 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e  rther control un
24490 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68  trusted SQL.  Th
244a0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
244b0 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65  tabase.** create
244c0 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65  d by an untruste
244d0 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20  d script can be 
244e0 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20  contained using 
244f0 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65  the.** [max_page
24500 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
24510 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d  ..**.** New run-
24520 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67  time limit categ
24530 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64  ories may be add
24540 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
24550 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  eases..*/.int sq
24560 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69  lite3_limit(sqli
24570 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e  te3*, int id, in
24580 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a  t newVal);../*.*
24590 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
245a0 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67  Time Limit Categ
245b0 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ories.** KEYWORD
245c0 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  S: {limit catego
245d0 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65  ry} {*limit cate
245e0 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  gories}.**.** Th
245f0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ese constants de
24600 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72  fine various per
24610 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a  formance limits.
24620 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c  ** that can be l
24630 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69  owered at run-ti
24640 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  me using [sqlite
24650 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54  3_limit()]..** T
24660 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74  he synopsis of t
24670 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74  he meanings of t
24680 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74  he various limit
24690 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77  s is shown below
246a0 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20  ..** Additional 
246b0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61  information is a
246c0 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d  vailable at [lim
246d0 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20  its | Limits in 
246e0 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  SQLite]..**.** <
246f0 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
24700 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e  LIMIT_LENGTH]] ^
24710 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
24720 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  T_LENGTH</dt>.**
24730 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
24740 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72   size of any str
24750 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74  ing or BLOB or t
24760 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74  able row, in byt
24770 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  es.<dd>)^.**.** 
24780 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  [[SQLITE_LIMIT_S
24790 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  QL_LENGTH]] ^(<d
247a0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  t>SQLITE_LIMIT_S
247b0 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  QL_LENGTH</dt>.*
247c0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
247d0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53  m length of an S
247e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e  QL statement, in
247f0 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a   bytes.</dd>)^.*
24800 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
24810 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c  MIT_COLUMN]] ^(<
24820 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
24830 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  COLUMN</dt>.** <
24840 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
24850 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
24860 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69   in a table defi
24870 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65  nition or in the
24880 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f  .** result set o
24890 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20  f a [SELECT] or 
248a0 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
248b0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
248c0 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20   an index.** or 
248d0 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f  in an ORDER BY o
248e0 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73  r GROUP BY claus
248f0 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
24900 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  [[SQLITE_LIMIT_E
24910 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  XPR_DEPTH]] ^(<d
24920 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  t>SQLITE_LIMIT_E
24930 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  XPR_DEPTH</dt>.*
24940 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
24950 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70  m depth of the p
24960 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79  arse tree on any
24970 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64   expression.</dd
24980 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
24990 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
249a0 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74  D_SELECT]] ^(<dt
249b0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
249c0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64  MPOUND_SELECT</d
249d0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
249e0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
249f0 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
24a00 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
24a10 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ment.</dd>)^.**.
24a20 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
24a30 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64  T_VDBE_OP]] ^(<d
24a40 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
24a50 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
24a60 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
24a70 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
24a80 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
24a90 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
24aa0 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
24ab0 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
24ac0 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20  tatement.  This 
24ad0 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72  limit is not cur
24ae0 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63  rently.** enforc
24af0 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20  ed, though that 
24b00 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69  might be added i
24b10 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
24b20 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
24b30 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  te.</dd>)^.**.**
24b40 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
24b50 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e  FUNCTION_ARG]] ^
24b60 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
24b70 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
24b80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
24b90 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
24ba0 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
24bb0 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  function.</dd>)^
24bc0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
24bd0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d  LIMIT_ATTACHED]]
24be0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
24bf0 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74  MIT_ATTACHED</dt
24c00 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
24c10 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b  imum number of [
24c20 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65  ATTACH | attache
24c30 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c  d databases].)^<
24c40 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
24c50 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
24c60 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a  ATTERN_LENGTH]].
24c70 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
24c80 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
24c90 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
24ca0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
24cb0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
24cc0 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
24cd0 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f   to the [LIKE] o
24ce0 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  r.** [GLOB] oper
24cf0 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ators.</dd>)^.**
24d00 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
24d10 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
24d20 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ER]].** ^(<dt>SQ
24d30 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
24d40 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
24d50 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
24d60 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20  um index number 
24d70 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65  of any [paramete
24d80 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  r] in an SQL sta
24d90 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  tement.)^.**.** 
24da0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  [[SQLITE_LIMIT_T
24db0 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e  RIGGER_DEPTH]] ^
24dc0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
24dd0 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c  T_TRIGGER_DEPTH<
24de0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
24df0 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
24e00 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74   recursion for t
24e10 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a  riggers.</dd>)^.
24e20 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
24e30 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
24e40 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
24e50 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
24e60 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
24e70 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20  T_SQL_LENGTH    
24e80 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
24e90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
24ea0 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20  IT_COLUMN       
24eb0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
24ec0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
24ed0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20  MIT_EXPR_DEPTH  
24ee0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a                3.
24ef0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
24f00 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
24f10 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34  LECT           4
24f20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24f30 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20  LIMIT_VDBE_OP   
24f40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24f50 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
24f60 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
24f70 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20  ARG             
24f80 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
24f90 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
24fa0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24fb0 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
24fc0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
24fd0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
24fe0 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
24ff0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
25000 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
25010 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
25020 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
25030 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  ER_DEPTH        
25040 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41      10../*.** CA
25050 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e  PI3REF: Compilin
25060 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  g An SQL Stateme
25070 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  nt.** KEYWORDS: 
25080 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63  {SQL statement c
25090 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54  ompiler}.**.** T
250a0 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c  o execute an SQL
250b0 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20   query, it must 
250c0 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65  first be compile
250d0 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f  d into a byte-co
250e0 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  de.** program us
250f0 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ing one of these
25100 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
25110 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
25120 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20  ent, "db", is a 
25130 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
25140 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66  tion] obtained f
25150 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73  rom a.** prior s
25160 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
25170 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
25180 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
25190 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  n_v2()] or.** [s
251a0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
251b0 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20  .  The database 
251c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
251d0 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c  not have been cl
251e0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  osed..**.** The 
251f0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c  second argument,
25200 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20   "zSql", is the 
25210 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
25220 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65  compiled, encode
25230 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55  d.** as either U
25240 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20  TF-8 or UTF-16. 
25250 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
25260 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74  pare() and sqlit
25270 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a  e3_prepare_v2().
25280 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73  ** interfaces us
25290 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c  e UTF-8, and sql
252a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
252b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
252c0 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75  pare16_v2().** u
252d0 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a  se UTF-16..**.**
252e0 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61   ^If the nByte a
252f0 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20  rgument is less 
25300 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20  than zero, then 
25310 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20  zSql is read up 
25320 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  to the.** first 
25330 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
25340 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f   ^If nByte is no
25350 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
25360 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d   it is the maxim
25370 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  um.** number of 
25380 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d   bytes read from
25390 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42   zSql.  ^When nB
253a0 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
253b0 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c  ive, the.** zSql
253c0 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20   string ends at 
253d0 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74  either the first
253e0 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30   '\000' or '\u00
253f0 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72  00' character or
25400 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68  .** the nByte-th
25410 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72   byte, whichever
25420 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66   comes first. If
25430 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77   the caller know
25440 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75  s.** that the su
25450 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73  pplied string is
25460 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c   nul-terminated,
25470 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61   then there is a
25480 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72   small.** perfor
25490 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20  mance advantage 
254a0 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20  to be gained by 
254b0 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65  passing an nByte
254c0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a   parameter that.
254d0 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74  ** is equal to t
254e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
254f0 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20  es in the input 
25500 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64  string <i>includ
25510 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e  ing</i>.** the n
25520 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79  ul-terminator by
25530 74 65 73 20 61 73 20 74 68 69 73 20 73 61 76 65  tes as this save
25540 73 20 53 51 4c 69 74 65 20 66 72 6f 6d 20 68 61  s SQLite from ha
25550 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20  ving to.** make 
25560 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 69 6e  a copy of the in
25570 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  put string..**.*
25580 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20  * ^If pzTail is 
25590 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70  not NULL then *p
255a0 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
255b0 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
255c0 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74  rst byte.** past
255d0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
255e0 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
255f0 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
25600 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c  ese routines onl
25610 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65  y.** compile the
25620 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74   first statement
25630 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a   in zSql, so *pz
25640 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69  Tail is left poi
25650 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74  nting to.** what
25660 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69   remains uncompi
25670 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53  led..**.** ^*ppS
25680 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  tmt is left poin
25690 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c  ting to a compil
256a0 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ed [prepared sta
256b0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e  tement] that can
256c0 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   be.** executed 
256d0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
256e0 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  tep()].  ^If the
256f0 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
25700 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a  *ppStmt is set.*
25710 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20  * to NULL.  ^If 
25720 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63  the input text c
25730 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28  ontains no SQL (
25740 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
25750 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69  an empty.** stri
25760 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29  ng or a comment)
25770 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73   then *ppStmt is
25780 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a   set to NULL..**
25790 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
257a0 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
257b0 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
257c0 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a  ng the compiled.
257d0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
257e0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
257f0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
25800 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
25810 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70  d with it..** pp
25820 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20  Stmt may not be 
25830 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20  NULL..**.** ^On 
25840 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c  success, the sql
25850 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66  ite3_prepare() f
25860 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65  amily of routine
25870 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
25880 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69  _OK];.** otherwi
25890 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
258a0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
258b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
258c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61  3_prepare_v2() a
258d0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
258e0 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66  re16_v2() interf
258f0 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f  aces are.** reco
25900 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
25910 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68  new programs. Th
25920 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65  e two older inte
25930 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69  rfaces are retai
25940 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77  ned.** for backw
25950 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
25960 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
25970 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
25980 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32  ..** ^In the "v2
25990 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
259a0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
259b0 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
259c0 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
259d0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
259e0 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
259f0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
25a00 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
25a10 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  . This causes th
25a20 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
25a30 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
25a40 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72  ** behave differ
25a50 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77  ently in three w
25a60 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
25a70 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
25a80 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
25a90 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
25aa0 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
25ab0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
25ac0 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
25ad0 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
25ae0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
25af0 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
25b00 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
25b10 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
25b20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
25b30 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79  t again. As many
25b40 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f   as [SQLITE_MAX_
25b50 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a  SCHEMA_RETRY].**
25b60 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63   retries will oc
25b70 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74  cur before sqlit
25b80 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20  e3_step() gives 
25b90 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  up and returns a
25ba0 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69  n error..** </li
25bb0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
25bc0 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f  ^When an error o
25bd0 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f  ccurs, [sqlite3_
25be0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74  step()] will ret
25bf0 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64  urn one of the d
25c00 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f  etailed.** [erro
25c10 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74  r codes] or [ext
25c20 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
25c30 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79  s].  ^The legacy
25c40 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68   behavior was th
25c50 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  at.** [sqlite3_s
25c60 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c  tep()] would onl
25c70 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72  y return a gener
25c80 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ic [SQLITE_ERROR
25c90 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a  ] result code.**
25ca0 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
25cb0 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20  tion would have 
25cc0 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
25cd0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
25ce0 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e  3_reset()].** in
25cf0 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74   order to find t
25d00 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
25d10 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
25d20 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32  em. With the "v2
25d30 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74  " prepare.** int
25d40 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
25d50 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
25d60 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20  or the error is 
25d70 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
25d80 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
25d90 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  *.** <li>.** ^If
25da0 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61   the specific va
25db0 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61  lue bound to [pa
25dc0 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70  rameter | host p
25dd0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
25de0 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73   .** WHERE claus
25df0 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  e might influenc
25e00 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20  e the choice of 
25e10 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61  query plan for a
25e20 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74   statement,.** t
25e30 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
25e40 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  t will be automa
25e50 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
25e60 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20  ed, as if there 
25e70 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73  had been .** a s
25e80 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e  chema change, on
25e90 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c   the first  [sql
25ea0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
25eb0 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20  l following any 
25ec0 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65  change.** to the
25ed0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
25ee0 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  ext | bindings] 
25ef0 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74  of that [paramet
25f00 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70  er]. .** ^The sp
25f10 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20  ecific value of 
25f20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61  WHERE-clause [pa
25f30 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69  rameter] might i
25f40 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a  nfluence the .**
25f50 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
25f60 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72   plan if the par
25f70 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65  ameter is the le
25f80 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ft-hand side of 
25f90 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b  a [LIKE].** or [
25fa0 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f  GLOB] operator o
25fb0 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  r if the paramet
25fc0 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74  er is compared t
25fd0 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c  o an indexed col
25fe0 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b  umn.** and the [
25ff0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54  SQLITE_ENABLE_ST
26000 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AT3] compile-tim
26010 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
26020 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  led..** </li>.**
26030 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71   </ol>.*/.int sq
26040 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
26050 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
26060 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
26070 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
26080 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
26090 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
260a0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
260b0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
260c0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
260d0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
260e0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
260f0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
26100 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
26110 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
26120 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
26130 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
26140 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
26150 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
26160 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
26170 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
26180 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
26190 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
261a0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
261b0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
261c0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
261d0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
261e0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
261f0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
26200 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
26210 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
26220 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
26230 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
26240 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
26250 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
26260 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
26270 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
26280 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
26290 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
262a0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
262b0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
262c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
262d0 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
262e0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
262f0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
26300 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
26310 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
26320 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
26330 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
26340 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
26350 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
26360 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
26370 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
26380 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
26390 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
263a0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
263b0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
263c0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
263d0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
263e0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
263f0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
26400 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
26410 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
26420 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
26430 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
26440 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
26450 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
26460 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
26470 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
26480 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
26490 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
264a0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
264b0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
264c0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
264d0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
264e0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
264f0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
26500 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
26510 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
26520 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
26530 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
26540 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
26550 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
26560 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
26570 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a  atement SQL.**.*
26580 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
26590 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
265a0 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65   retrieve a save
265b0 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72  d copy of the or
265c0 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65  iginal.** SQL te
265d0 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74  xt used to creat
265e0 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
265f0 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74  atement] if that
26600 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a   statement was.*
26610 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67  * compiled using
26620 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
26630 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
26640 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
26650 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63  re16_v2()]..*/.c
26660 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
26670 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  e3_sql(sqlite3_s
26680 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
26690 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
266a0 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
266b0 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74  L Statement Writ
266c0 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a  es The Database.
266d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
266e0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
266f0 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (X) interface re
26700 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
26710 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20  zero) if.** and 
26720 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65  only if the [pre
26730 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26740 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65   X makes no dire
26750 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a  ct changes to.**
26760 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
26770 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
26780 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  e..**.** Note th
26790 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  at [application-
267a0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
267b0 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69  tions] or.** [vi
267c0 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69  rtual tables] mi
267d0 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  ght change the d
267e0 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74  atabase indirect
267f0 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66  ly as a side eff
26800 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20  ect.  .** ^(For 
26810 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61  example, if an a
26820 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
26830 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65  es a function "e
26840 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20  val()" that .** 
26850 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65  calls [sqlite3_e
26860 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  xec()], then the
26870 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73   following SQL s
26880 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a  tatement would.*
26890 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  * change the dat
268a0 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75  abase file throu
268b0 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a  gh side-effects:
268c0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
268d0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53  te><pre>.**    S
268e0 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45  ELECT eval('DELE
268f0 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f  TE FROM t1') FRO
26900 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  M t2;.** </pre><
26910 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
26920 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74  ** But because t
26930 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
26940 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
26950 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
26960 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63  se file.** direc
26970 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  tly, sqlite3_stm
26980 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75  t_readonly() wou
26990 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20  ld still return 
269a0 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  true.)^.**.** ^T
269b0 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
269c0 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75  ol statements su
269d0 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b  ch as [BEGIN], [
269e0 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41  COMMIT], [ROLLBA
269f0 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49  CK],.** [SAVEPOI
26a00 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53  NT], and [RELEAS
26a10 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33  E] cause sqlite3
26a20 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
26a30 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c   to return true,
26a40 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74  .** since the st
26a50 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c  atements themsel
26a60 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61  ves do not actua
26a70 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64  lly modify the d
26a80 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72  atabase but.** r
26a90 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72  ather they contr
26aa0 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66  ol the timing of
26ab0 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74   when other stat
26ac0 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68  ements modify th
26ad0 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  e .** database. 
26ae0 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61   ^The [ATTACH] a
26af0 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74  nd [DETACH] stat
26b00 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73  ements also caus
26b10 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  e.** sqlite3_stm
26b20 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
26b30 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63  return true sinc
26b40 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73  e, while those s
26b50 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61  tatements.** cha
26b60 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72  nge the configur
26b70 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62  ation of a datab
26b80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
26b90 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65  they do not make
26ba0 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20   .** changes to 
26bb0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
26bc0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
26bd0 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e  s on disk..*/.in
26be0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  t sqlite3_stmt_r
26bf0 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f  eadonly(sqlite3_
26c00 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
26c10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
26c20 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72  etermine If A Pr
26c30 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
26c40 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a   Has Been Reset.
26c50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
26c60 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20  e3_stmt_busy(S) 
26c70 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
26c80 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
26c90 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ) if the.** [pre
26ca0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26cb0 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70   S has been step
26cc0 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63  ped at least onc
26cd0 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  e using .** [sql
26ce0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75  ite3_step(S)] bu
26cf0 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f  t has not run to
26d00 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f   completion and/
26d10 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62  or has not .** b
26d20 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20  een reset using 
26d30 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
26d40 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  )].  ^The sqlite
26d50 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a  3_stmt_busy(S).*
26d60 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
26d70 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69  rns false if S i
26d80 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
26d90 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61  .  If S is not a
26da0 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   .** NULL pointe
26db0 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  r and is not a p
26dc0 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69  ointer to a vali
26dd0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
26de0 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
26df0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
26e00 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
26e10 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e   and probably un
26e20 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  desirable..**.**
26e30 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
26e40 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63  can be used in c
26e50 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69  ombination [sqli
26e60 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d  te3_next_stmt()]
26e70 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c  .** to locate al
26e80 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  l prepared state
26e90 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64  ments associated
26ea0 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65   with a database
26eb0 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   .** connection 
26ec0 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64  that are in need
26ed0 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e   of being reset.
26ee0 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73    This can be us
26ef0 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70  ed,.** for examp
26f00 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69  le, in diagnosti
26f10 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65  c routines to se
26f20 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65  arch for prepare
26f30 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  d .** statements
26f40 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e   that are holdin
26f50 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  g a transaction 
26f60 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  open..*/.int sql
26f70 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73  ite3_stmt_busy(s
26f80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
26f90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26fa0 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
26fb0 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a  d Value Object.*
26fc0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
26fd0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
26fe0 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
26ff0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
27000 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
27010 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
27020 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
27030 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
27040 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
27050 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
27060 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
27070 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
27080 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
27090 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
270a0 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73  stores.  ^Values
270b0 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
270c0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
270d0 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67  .** can be integ
270e0 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
270f0 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
27100 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
27110 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
27120 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
27130 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
27140 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
27150 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
27160 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
27170 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
27180 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
27190 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
271a0 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
271b0 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
271c0 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
271d0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
271e0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
271f0 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
27200 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
27210 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
27220 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  s specifies.** w
27230 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
27240 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74   requires a prot
27250 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
27260 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  lue..**.** The t
27270 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22  erms "protected"
27280 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65   and "unprotecte
27290 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74  d" refer to whet
272a0 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20  her or not.** a 
272b0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20  mutex is held.  
272c0 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65  An internal mute
272d0 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
272e0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
272f0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
27300 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
27310 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
27320 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
27330 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
27340 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
27350 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
27360 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
27370 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
27380 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
27390 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
273a0 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
273b0 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
273c0 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
273d0 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
273e0 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
273f0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
27400 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
27410 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
27420 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
27430 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
27440 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
27450 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
27460 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
27470 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
27480 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
27490 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
274a0 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
274b0 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
274c0 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
274d0 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
274e0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
274f0 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
27500 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
27510 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
27520 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
27530 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
27540 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
27550 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68   objects even wh
27560 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  en not strictly 
27570 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
27580 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
27590 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
275a0 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
275b0 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
275c0 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
275d0 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
275e0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
275f0 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
27600 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68  rotected..** ^Th
27610 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
27620 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
27630 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
27640 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
27650 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a  s unprotected..*
27660 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71  * Unprotected sq
27670 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
27680 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  cts may only be 
27690 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71  used with.** [sq
276a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
276b0 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
276c0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
276d0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
276e0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73  3_value_blob | s
276f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
27700 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  e()] family of.*
27710 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  * interfaces req
27720 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73  uire protected s
27730 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
27740 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ects..*/.typedef
27750 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69   struct Mem sqli
27760 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
27770 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
27780 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
27790 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
277a0 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
277b0 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
277c0 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
277d0 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
277e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
277f0 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74  bject.  ^A point
27800 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
27810 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
27820 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
27830 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
27840 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
27850 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
27860 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
27870 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
27880 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
27890 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
278a0 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
278b0 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
278c0 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
278d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
278e0 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
278f0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
27900 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
27910 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
27920 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
27930 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
27940 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
27950 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
27960 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
27970 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
27980 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
27990 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
279a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
279b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
279c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
279d0 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
279e0 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
279f0 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ments.** KEYWORD
27a00 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
27a10 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
27a20 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
27a30 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
27a40 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
27a50 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
27a60 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
27a70 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
27a80 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c  .** ^(In the SQL
27a90 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
27aa0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
27ab0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
27ac0 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
27ad0 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
27ae0 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
27af0 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74   a [parameter] t
27b00 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20  hat matches one 
27b10 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  of following.** 
27b20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a  templates:.**.**
27b30 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
27b40 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
27b50 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
27b60 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
27b70 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
27b80 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74  >.**.** In the t
27b90 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20  emplates above, 
27ba0 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61  NNN represents a
27bb0 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
27bc0 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65  l,.** and VVV re
27bd0 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68  presents an alph
27be0 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66  anumeric identif
27bf0 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c  ier.)^  ^The val
27c00 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ues of these.** 
27c10 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
27c20 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
27c30 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f  rameter names" o
27c40 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
27c50 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
27c60 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
27c70 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
27c80 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
27c90 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  re..**.** ^The f
27ca0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
27cb0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
27cc0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69  d_*() routines i
27cd0 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f  s always.** a po
27ce0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
27cf0 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
27d00 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ct returned from
27d10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
27d20 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74  pare_v2()] or it
27d30 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a  s variants..**.*
27d40 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  * ^The second ar
27d50 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
27d60 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70  dex of the SQL p
27d70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73  arameter to be s
27d80 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  et..** ^The left
27d90 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
27da0 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
27db0 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65  of 1.  ^When the
27dc0 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53   same named.** S
27dd0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
27de0 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  used more than o
27df0 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20  nce, second and 
27e00 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63  subsequent.** oc
27e10 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74  currences have t
27e20 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73  he same index as
27e30 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
27e40 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69  rence..** ^The i
27e50 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70  ndex for named p
27e60 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
27e70 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
27e80 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
27e90 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
27ea0 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20  index()] API if 
27eb0 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69  desired.  ^The i
27ec0 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e  ndex.** for "?NN
27ed0 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  N" parameters is
27ee0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e   the value of NN
27ef0 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76  N..** ^The NNN v
27f00 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
27f10 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b  ween 1 and the [
27f20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
27f30 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53  .** parameter [S
27f40 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
27f50 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65  ABLE_NUMBER] (de
27f60 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
27f70 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  )..**.** ^The th
27f80 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
27f90 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e  the value to bin
27fa0 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  d to the paramet
27fb0 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
27fc0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
27fd0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
27fe0 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
27ff0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a  _bind_text16().*
28000 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
28010 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55  d_blob() is a NU
28020 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
28030 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
28040 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72  eter.** is ignor
28050 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72  ed and the end r
28060 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d  esult is the sam
28070 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e  e as sqlite3_bin
28080 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20  d_null()..**.** 
28090 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69  ^(In those routi
280a0 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
280b0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
280c0 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
280d0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
280e0 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61  ytes in the para
280f0 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
28100 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
28110 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
28120 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20  of <u>bytes</u> 
28130 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
28140 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
28150 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a  characters.)^.**
28160 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
28170 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
28180 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
28190 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
281a0 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20  _text16().** is 
281b0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
281c0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
281d0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68   string is.** th
281e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
281f0 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  s up to the firs
28200 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
28210 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75  r..** If the fou
28220 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
28230 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
28240 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  ob() is negative
28250 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65  , then.** the be
28260 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
28270 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e  ned..** If a non
28280 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68  -negative fourth
28290 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
282a0 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65  ovided to sqlite
282b0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a  3_bind_text().**
282c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
282d0 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e 20 74  _text16() then t
282e0 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  hat parameter mu
282f0 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
28300 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74  ffset.** where t
28310 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
28320 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73  r would occur as
28330 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e  suming the strin
28340 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65  g were NUL.** te
28350 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
28360 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
28370 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f   occur at byte o
28380 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e  ffsets less than
28390 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f   .** the value o
283a0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
283b0 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20  ameter then the 
283c0 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
283d0 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63   value will.** c
283e0 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
283f0 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c  NULs.  The resul
28400 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
28410 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e   involving strin
28420 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64  gs.** with embed
28430 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
28440 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
28450 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
28460 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
28470 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
28480 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e  _bind_text(), an
28490 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e  d.** sqlite3_bin
284a0 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20  d_text16() is a 
284b0 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
284c0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
284d0 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
284e0 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
284f0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
28500 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73  th it.  ^The des
28510 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
28520 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20  d.** to dispose 
28530 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
28540 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  tring even if th
28550 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  e call to sqlite
28560 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a  3_bind_blob(),.*
28570 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  * sqlite3_bind_t
28580 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  ext(), or sqlite
28590 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
285a0 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20  fails.  .** ^If 
285b0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
285c0 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
285d0 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
285e0 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
285f0 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
28600 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
28610 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
28620 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
28630 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
28640 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
28650 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  eed..** ^If the 
28660 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
28670 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
28680 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
28690 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
286a0 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
286b0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
286c0 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
286d0 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
286e0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
286f0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
28700 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
28710 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
28720 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
28730 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
28740 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
28750 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
28760 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
28770 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
28780 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
28790 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
287a0 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
287b0 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
287c0 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
287d0 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
287e0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
287f0 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
28800 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
28810 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
28820 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
28830 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
28840 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
28850 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
28860 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
28870 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
28880 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
28890 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
288a0 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
288b0 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   BLOB..**.** ^If
288c0 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69   any of the sqli
288d0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
288e0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
288f0 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
28900 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20  nter.** for the 
28910 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28920 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70  ent] or with a p
28930 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28940 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b  t for which.** [
28950 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
28960 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  has been called 
28970 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68  more recently th
28980 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  an [sqlite3_rese
28990 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  t()],.** then th
289a0 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75  e call will retu
289b0 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  rn [SQLITE_MISUS
289c0 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69  E].  If any sqli
289d0 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72  te3_bind_().** r
289e0 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64  outine is passed
289f0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
28a00 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
28a10 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c   been finalized,
28a20 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69   the.** result i
28a30 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
28a40 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c  probably harmful
28a50 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67  ..**.** ^Binding
28a60 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
28a70 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
28a80 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
28a90 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20  ne..** ^Unbound 
28aa0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69  parameters are i
28ab0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55  nterpreted as NU
28ac0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
28ad0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f  qlite3_bind_* ro
28ae0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
28af0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
28b00 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  cess or an.** [e
28b10 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e  rror code] if an
28b20 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ything goes wron
28b30 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52  g..** ^[SQLITE_R
28b40 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
28b50 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
28b60 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
28b70 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b  ut of range.  ^[
28b80 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
28b90 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
28ba0 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a  loc() fails..**.
28bb0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
28bc0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
28bd0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
28be0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
28bf0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
28c00 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
28c10 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
28c20 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
28c30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
28c40 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
28c50 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
28c60 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
28c70 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
28c80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
28c90 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
28ca0 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
28cb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
28cc0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
28cd0 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
28ce0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
28cf0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
28d00 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
28d10 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71  3_int64);.int sq
28d20 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
28d30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
28d40 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
28d50 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
28d60 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
28d70 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20  onst char*, int 
28d80 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
28d90 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
28da0 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
28db0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
28dc0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
28dd0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
28de0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
28df0 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
28e00 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
28e10 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
28e20 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
28e30 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
28e40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
28e50 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  t, int n);../*.*
28e60 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
28e70 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
28e80 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ters.**.** ^This
28e90 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
28ea0 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
28eb0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
28ec0 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
28ed0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
28ee0 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
28ef0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
28f00 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
28f10 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
28f20 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
28f30 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
28f40 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
28f50 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
28f60 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
28f70 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
28f80 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
28f90 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
28fa0 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
28fb0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
28fc0 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
28fd0 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
28fe0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
28ff0 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
29000 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
29010 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
29020 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
29030 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
29040 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
29050 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
29060 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
29070 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61   the ?NNN form a
29080 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
29090 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
290a0 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a   the list.)^.**.
290b0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
290c0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
290d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
290e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
290f0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
29100 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
29110 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
29120 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
29130 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
29140 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
29150 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
29160 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29170 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
29180 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a  t Parameter.**.*
29190 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
291a0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
291b0 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63  me(P,N) interfac
291c0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  e returns.** the
291d0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74   name of the N-t
291e0 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  h [SQL parameter
291f0 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] in the [prepar
29200 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
29210 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65  .** ^(SQL parame
29220 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
29230 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
29240 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
29250 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20  $AAA".** have a 
29260 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68  name which is th
29270 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20  e string "?NNN" 
29280 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
29290 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
292a0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
292b0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
292c0 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a  , the initial ":
292d0 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20  " or "$" or "@" 
292e0 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63  or "?".** is inc
292f0 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66  luded as part of
29300 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20   the name.)^.** 
29310 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74  ^Parameters of t
29320 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68  he form "?" with
29330 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20  out a following 
29340 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20  integer have no 
29350 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20  name.** and are 
29360 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22  referred to as "
29370 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e  nameless" or "an
29380 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65  onymous paramete
29390 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rs"..**.** ^The 
293a0 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d  first host param
293b0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
293c0 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a  x of 1, not 0..*
293d0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c  *.** ^If the val
293e0 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72  ue N is out of r
293f0 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e  ange or if the N
29400 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  -th parameter is
29410 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68  .** nameless, th
29420 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  en NULL is retur
29430 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ned.  ^The retur
29440 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  ned string is.**
29450 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38   always in UTF-8
29460 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69   encoding even i
29470 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61  f the named para
29480 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69  meter was.** ori
29490 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65  ginally specifie
294a0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b  d as UTF-16 in [
294b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
294c0 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  6()] or.** [sqli
294d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
294e0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
294f0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
29500 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
29510 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
29520 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
29530 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
29540 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
29550 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
29560 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  ex()]..*/.const 
29570 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69  char *sqlite3_bi
29580 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
29590 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
295a0 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   int);../*.** CA
295b0 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66  PI3REF: Index Of
295c0 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74   A Parameter Wit
295d0 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a  h A Given Name.*
295e0 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
295f0 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
29600 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
29610 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65   its name.  ^The
29620 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20  .** index value 
29630 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74  returned is suit
29640 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20  able for use as 
29650 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61  the second.** pa
29660 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
29670 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
29680 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20  lite3_bind()].  
29690 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65  ^A zero.** is re
296a0 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
296b0 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
296c0 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20  is found.  ^The 
296d0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d  parameter.** nam
296e0 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20  e must be given 
296f0 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66  in UTF-8 even if
29700 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
29710 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70  atement.** was p
29720 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46  repared from UTF
29730 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b  -16 text using [
29740 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
29750 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
29760 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
29770 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
29780 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
29790 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
297a0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
297b0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
297c0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
297d0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
297e0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
297f0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
29800 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
29810 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
29820 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29830 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
29840 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
29850 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
29860 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f  .** ^Contrary to
29870 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
29880 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
29890 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
298a0 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20  ot reset.** the 
298b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
298c0 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
298d0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
298e0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73  atement]..** ^Us
298f0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
29900 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
29910 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
29920 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
29930 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
29940 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
29950 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
29960 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
29970 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
29980 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  t Set.**.** ^Ret
29990 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
299a0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
299b0 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
299c0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  rned by the.** [
299d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
299e0 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69  nt]. ^This routi
299f0 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
29a00 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a  pStmt is an SQL.
29a10 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
29a20 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72  t does not retur
29a30 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  n data (for exam
29a40 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29  ple an [UPDATE])
29a50 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
29a60 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  : [sqlite3_data_
29a70 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20  count()].*/.int 
29a80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
29a90 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
29aa0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
29ab0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
29ac0 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
29ad0 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult Set.**.** ^
29ae0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
29af0 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61  eturn the name a
29b00 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72  ssigned to a par
29b10 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a  ticular column.*
29b20 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  * in the result 
29b30 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
29b40 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54  ] statement.  ^T
29b50 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
29b60 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
29b70 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
29b80 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
29b90 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
29ba0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
29bb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29bc0 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
29bd0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
29be0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
29bf0 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
29c00 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  .  ^The first pa
29c10 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
29c20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29c30 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c  nt].** that impl
29c40 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45  ements the [SELE
29c50 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e  CT] statement. ^
29c60 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
29c70 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63  eter is the.** c
29c80 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e  olumn number.  ^
29c90 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
29ca0 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e  umn is number 0.
29cb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  .**.** ^The retu
29cc0 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
29cd0 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
29ce0 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
29cf0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29d00 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
29d10 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
29d20 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
29d30 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
29d40 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
29d50 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
29d60 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
29d70 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
29d80 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
29d90 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
29da0 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  r until the next
29db0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
29dc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
29dd0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
29de0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20  umn_name16() on 
29df0 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
29e00 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  .**.** ^If sqlit
29e10 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
29e20 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
29e30 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
29e40 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
29e50 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
29e60 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
29e70 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
29e80 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
29e90 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
29ea0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
29eb0 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73  he name of a res
29ec0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  ult column is th
29ed0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22  e value of the "
29ee0 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a  AS" clause for.*
29ef0 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69  * that column, i
29f00 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53  f there is an AS
29f10 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65   clause.  If the
29f20 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75  re is no AS clau
29f30 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e  se.** then the n
29f40 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  ame of the colum
29f50 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64  n is unspecified
29f60 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20   and may change 
29f70 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65  from.** one rele
29f80 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f  ase of SQLite to
29f90 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f   the next..*/.co
29fa0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
29fb0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71  3_column_name(sq
29fc0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
29fd0 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20   N);.const void 
29fe0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
29ff0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2a000 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f  tmt*, int N);../
2a010 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
2a020 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e  ource Of Data In
2a030 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
2a040 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2a050 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
2a060 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
2a070 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c  ne the database,
2a080 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74   table, and.** t
2a090 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
2a0a0 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f   is the origin o
2a0b0 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  f a particular r
2a0c0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a  esult column in.
2a0d0 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  ** [SELECT] stat
2a0e0 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e  ement..** ^The n
2a0f0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
2a100 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
2a110 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
2a120 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
2a130 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55  her a UTF-8 or U
2a140 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
2a150 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
2a160 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
2a170 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
2a180 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
2a190 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2a1a0 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
2a1b0 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
2a1c0 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
2a1d0 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
2a1e0 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ame..** ^The ret
2a1f0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
2a200 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
2a210 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a220 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65  ent] is destroye
2a230 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
2a240 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2a250 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
2a260 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
2a270 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
2a280 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
2a290 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
2a2a0 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
2a2b0 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
2a2c0 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
2a2d0 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
2a2e0 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
2a2f0 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
2a300 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
2a310 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
2a320 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
2a330 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
2a340 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
2a350 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
2a360 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
2a370 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  mn..**.** ^The f
2a380 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
2a390 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
2a3a0 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  s is a [prepared
2a3b0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2a3c0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
2a3d0 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
2a3e0 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
2a3f0 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
2a400 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74  returned by.** t
2a410 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68  he statement, wh
2a420 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
2a430 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
2a440 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  ument..** ^The l
2a450 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
2a460 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20  is column 0 for 
2a470 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
2a480 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74  **.** ^If the Nt
2a490 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
2a4a0 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
2a4b0 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
2a4c0 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65  ion or.** subque
2a4d0 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
2a4e0 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
2a4f0 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
2a500 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2a510 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73  .** NULL.  ^Thes
2a520 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
2a530 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
2a540 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
2a550 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a  ocation error.**
2a560 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72   occurs.  ^Other
2a570 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
2a580 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
2a590 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
2a5a0 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f  ase, table,.** o
2a5b0 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  r column that qu
2a5c0 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
2a5d0 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
2a5e0 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  from..**.** ^As 
2a5f0 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53  with all other S
2a600 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73  QLite APIs, thos
2a610 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e  e whose names en
2a620 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
2a630 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
2a640 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64  oded strings and
2a650 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74   the other funct
2a660 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d  ions return UTF-
2a670 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  8..**.** ^These 
2a680 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76  APIs are only av
2a690 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
2a6a0 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
2a6b0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
2a6c0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
2a6d0 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
2a6e0 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
2a6f0 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ymbol..**.** If 
2a700 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
2a710 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
2a720 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f  more of these ro
2a730 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74  utines against t
2a740 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61  he same.** prepa
2a750 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
2a760 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20  d column at the 
2a770 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
2a780 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a  he results are.*
2a790 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
2a7a0 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
2a7b0 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
2a7c0 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73  ne or more.** [s
2a7d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
2a7e0 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f  tabase_name | co
2a7f0 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e  lumn metadata in
2a800 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72  terfaces].** for
2a810 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61   the same [prepa
2a820 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
2a830 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  nd result column
2a840 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20  .** at the same 
2a850 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
2a860 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2a870 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ned..*/.const ch
2a880 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2a890 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2a8a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2a8b0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
2a8c0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2a8d0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
2a8e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2a8f0 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
2a900 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2a910 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
2a920 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2a930 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2a940 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
2a950 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2a960 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2a970 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2a980 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
2a990 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2a9a0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
2a9b0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2a9c0 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
2a9d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2a9e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2a9f0 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
2aa00 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
2aa10 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54  Result.**.** ^(T
2aa20 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2aa30 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
2aa40 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2aa50 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
2aa60 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
2aa70 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
2aa80 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
2aa90 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
2aaa0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
2aab0 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
2aac0 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
2aad0 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
2aae0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
2aaf0 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
2ab00 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
2ab10 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
2ab20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20  is returned.)^  
2ab30 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
2ab40 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
2ab50 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
2ab60 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
2ab70 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
2ab80 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
2ab90 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72  urned..** ^The r
2aba0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2abb0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
2abc0 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ncoded..**.** ^(
2abd0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
2abe0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
2abf0 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
2ac00 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
2ac10 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
2ac20 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
2ac30 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
2ac40 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
2ac50 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
2ac60 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
2ac70 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
2ac80 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
2ac90 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
2aca0 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
2acb0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
2acc0 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
2acd0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
2ace0 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
2acf0 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
2ad00 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
2ad10 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
2ad20 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
2ad30 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73   ^So just becaus
2ad40 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
2ad50 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
2ad60 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
2ad70 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
2ad80 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
2ad90 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
2ada0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
2adb0 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
2adc0 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
2add0 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
2ade0 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
2adf0 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
2ae00 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a   static.  ^Type.
2ae10 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
2ae20 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
2ae30 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
2ae40 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
2ae50 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
2ae60 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
2ae70 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
2ae80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
2ae90 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  ltype(sqlite3_st
2aea0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2aeb0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2aec0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
2aed0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2aee0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2aef0 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e  REF: Evaluate An
2af00 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
2af10 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72  *.** After a [pr
2af20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2af30 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61  ] has been prepa
2af40 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  red using either
2af50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2af60 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2af70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2af80 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
2af90 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
2afa0 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
2afb0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
2afc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2afd0 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e  e16()], this fun
2afe0 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65  ction.** must be
2aff0 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
2b000 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61  ore times to eva
2b010 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  luate the statem
2b020 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
2b030 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
2b040 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71  havior of the sq
2b050 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
2b060 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
2b070 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
2b080 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
2b090 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
2b0a0 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65   newer "v2" inte
2b0b0 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  rface.** [sqlite
2b0c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2b0d0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2b0e0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
2b0f0 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79  the older legacy
2b100 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73  .** interface [s
2b110 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2b120 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2b130 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68  repare16()].  Th
2b140 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20  e use of the.** 
2b150 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61  new "v2" interfa
2b160 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2b170 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63  d for new applic
2b180 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c  ations but the l
2b190 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
2b1a0 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65  ce will continue
2b1b0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
2b1c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ..**.** ^In the 
2b1d0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
2b1e0 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2b1f0 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
2b200 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
2b210 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
2b220 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
2b230 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
2b240 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
2b250 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  SE]..** ^With th
2b260 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2b270 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
2b280 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  er [result codes
2b290 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
2b2a0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
2b2b0 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
2b2c0 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a  d as well..**.**
2b2d0 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20   ^[SQLITE_BUSY] 
2b2e0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
2b2f0 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
2b300 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
2b310 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
2b320 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
2b330 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
2b340 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74  b.  ^If the stat
2b350 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d  ement is a [COMM
2b360 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  IT].** or occurs
2b370 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
2b380 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
2b390 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
2b3a0 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
2b3b0 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
2b3c0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
2b3d0 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e  ot a [COMMIT] an
2b3e0 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  d occurs within 
2b3f0 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74  an.** explicit t
2b400 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
2b410 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
2b420 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
2b430 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
2b440 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
2b450 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d  ^[SQLITE_DONE] m
2b460 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
2b470 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
2b480 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
2b490 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
2b4a0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2b4b0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
2b4c0 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
2b4d0 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
2b4e0 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
2b4f0 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
2b500 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
2b510 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
2b520 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
2b530 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
2b540 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  l state..**.** ^
2b550 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
2b560 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75  ment being execu
2b570 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ted returns any 
2b580 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49  data, then [SQLI
2b590 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65  TE_ROW].** is re
2b5a0 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
2b5b0 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
2b5c0 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20  ta is ready for 
2b5d0 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68  processing by th
2b5e0 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65  e.** caller. The
2b5f0 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
2b600 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68  ccessed using th
2b610 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  e [column access
2b620 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
2b630 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
2b640 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74  s called again t
2b650 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e  o retrieve the n
2b660 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e  ext row of data.
2b670 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2b680 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
2b690 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
2b6a0 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
2b6b0 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
2b6c0 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
2b6d0 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
2b6e0 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
2b6f0 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
2b700 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
2b710 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
2b720 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
2b730 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2b740 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57  errmsg()]..** ^W
2b750 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
2b760 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
2b770 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
2b780 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c  code (for exampl
2b790 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e,.** [SQLITE_IN
2b7a0 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54  TERRUPT], [SQLIT
2b7b0 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49  E_SCHEMA], [SQLI
2b7c0 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64  TE_CORRUPT], and
2b7d0 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61   so forth).** ca
2b7e0 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79  n be obtained by
2b7f0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2b800 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68  3_reset()] on th
2b810 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2b820 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20  tatement].  ^In 
2b830 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2b840 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
2b850 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
2b860 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
2b870 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
2b880 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
2b890 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
2b8a0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2b8b0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
2b8c0 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
2b8d0 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
2b8e0 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
2b8f0 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
2b900 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2b910 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
2b920 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
2b930 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
2b940 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
2b950 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
2b960 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
2b970 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
2b980 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
2b990 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
2b9a0 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
2b9b0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2b9c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2b9d0 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
2b9e0 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
2b9f0 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
2ba00 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
2ba10 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20  ..**.** For all 
2ba20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
2ba30 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63  te up to and inc
2ba40 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c  luding 3.6.23.1,
2ba50 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
2ba60 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2ba70 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74  was required aft
2ba80 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  er sqlite3_step(
2ba90 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68  ) returned anyth
2baa0 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61  ing.** other tha
2bab0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62  n [SQLITE_ROW] b
2bac0 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71  efore any subseq
2bad0 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20  uent invocation 
2bae0 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  of.** sqlite3_st
2baf0 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74  ep().  Failure t
2bb00 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  o reset the prep
2bb10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
2bb20 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
2bb30 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64  3_reset()] would
2bb40 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53   result in an [S
2bb50 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65  QLITE_MISUSE] re
2bb60 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  turn from.** sql
2bb70 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75  ite3_step().  Bu
2bb80 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20  t after version 
2bb90 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65  3.6.23.1, sqlite
2bba0 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a  3_step() began.*
2bbb0 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * calling [sqlit
2bbc0 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f  e3_reset()] auto
2bbd0 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69  matically in thi
2bbe0 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72  s circumstance r
2bbf0 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65  ather.** than re
2bc00 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
2bc10 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69  MISUSE].  This i
2bc20 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64  s not considered
2bc30 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79   a compatibility
2bc40 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73  .** break becaus
2bc50 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f  e any applicatio
2bc60 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65  n that ever rece
2bc70 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d  ives an SQLITE_M
2bc80 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69  ISUSE error.** i
2bc90 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69  s broken by defi
2bca0 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51  nition.  The [SQ
2bcb0 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45  LITE_OMIT_AUTORE
2bcc0 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  SET] compile-tim
2bcd0 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20  e option.** can 
2bce0 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f  be used to resto
2bcf0 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  re the legacy be
2bd00 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  havior..**.** <b
2bd10 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
2bd20 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74   Alert:</b> In t
2bd30 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
2bd40 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ace, the sqlite3
2bd50 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61  _step().** API a
2bd60 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
2bd70 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f  generic error co
2bd80 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  de, [SQLITE_ERRO
2bd90 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
2bda0 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72  y.** error other
2bdb0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55   than [SQLITE_BU
2bdc0 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  SY] and [SQLITE_
2bdd0 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
2bde0 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  st call.** [sqli
2bdf0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
2be00 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2be10 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
2be20 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
2be30 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72  .** specific [er
2be40 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ror codes] that 
2be50 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
2be60 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
2be70 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
2be80 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
2be90 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
2bea0 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
2beb0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
2bec0 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
2bed0 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
2bee0 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
2bef0 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
2bf00 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
2bf10 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2bf20 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2bf30 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65  re16_v2()] inste
2bf40 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67  ad.** of the leg
2bf50 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  acy [sqlite3_pre
2bf60 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
2bf70 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2bf80 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a  ] interfaces,.**
2bf90 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73   then the more s
2bfa0 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
2bfb0 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e  odes] are return
2bfc0 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62  ed directly.** b
2bfd0 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
2bfe0 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
2bff0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2c000 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e   is recommended.
2c010 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2c020 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
2c030 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2c040 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
2c050 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
2c060 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  ult set.**.** ^T
2c070 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2c080 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61  count(P) interfa
2c090 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
2c0a0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2c0b0 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   in the.** curre
2c0c0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2c0d0 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65  sult set of [pre
2c0e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c0f0 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61   P..** ^If prepa
2c100 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20  red statement P 
2c110 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65  does not have re
2c120 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72  sults ready to r
2c130 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61  eturn.** (via ca
2c140 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  lls to the [sqli
2c150 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c  te3_column_int |
2c160 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c170 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  *()] of.** inter
2c180 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69  faces) then sqli
2c190 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2c1a0 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20  ) returns 0..** 
2c1b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2c1c0 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
2c1d0 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20  ne also returns 
2c1e0 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c  0 if P is a NULL
2c1f0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68   pointer..** ^Th
2c200 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2c210 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
2c220 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65  returns 0 if the
2c230 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2c240 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
2c250 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20  ep](P) returned 
2c260 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
2c270 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2c280 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69  a_count(P).** wi
2c290 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65  ll return non-ze
2c2a0 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63  ro if previous c
2c2b0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2c2c0 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
2c2d0 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57  d.** [SQLITE_ROW
2c2e0 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65  ], except in the
2c2f0 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52   case of the [PR
2c300 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c  AGMA incremental
2c310 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72  _vacuum].** wher
2c320 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  e it always retu
2c330 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65  rns zero since e
2c340 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74  ach step of that
2c350 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70   multi-step.** p
2c360 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20  ragma returns 0 
2c370 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e  columns of data.
2c380 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2c390 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2c3a0 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74  _count()].*/.int
2c3b0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2c3c0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
2c3d0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2c3e0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
2c3f0 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
2c400 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
2c410 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
2c420 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  ^(Every value in
2c430 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
2c440 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
2c450 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
2c460 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2c470 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
2c480 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
2c490 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
2c4a0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
2c4b0 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
2c4c0 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
2c4d0 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
2c4e0 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ul>)^.**.** Thes
2c4f0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
2c500 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
2c510 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
2c520 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
2c530 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
2c540 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
2c550 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
2c560 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
2c570 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
2c580 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
2c590 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
2c5a0 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
2c5b0 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
2c5c0 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
2c5d0 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
2c5e0 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
2c5f0 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  EXT, not.** SQLI
2c600 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
2c610 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
2c620 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
2c630 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
2c640 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
2c650 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
2c660 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
2c670 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
2c680 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
2c690 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
2c6a0 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
2c6b0 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
2c6c0 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
2c6d0 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
2c6e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2c6f0 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f  esult Values Fro
2c700 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59  m A Query.** KEY
2c710 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
2c720 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
2c730 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2c740 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22  tines form the "
2c750 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65  result set" inte
2c760 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rface..**.** ^Th
2c770 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
2c780 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
2c790 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63  about a single c
2c7a0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
2c7b0 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72  rent.** result r
2c7c0 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
2c7d0 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74  ^In every case t
2c7e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2c7f0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  t is a pointer.*
2c800 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  * to the [prepar
2c810 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2c820 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c  at is being eval
2c830 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
2c840 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68  te3_stmt*].** th
2c850 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
2c860 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72  from [sqlite3_pr
2c870 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f  epare_v2()] or o
2c880 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
2c890 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73  ts).** and the s
2c8a0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
2c8b0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
2c8c0 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68  he column for wh
2c8d0 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ich information.
2c8e0 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
2c8f0 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74  urned. ^The left
2c900 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  most column of t
2c910 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61  he result set ha
2c920 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a  s the index 0..*
2c930 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  * ^The number of
2c940 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
2c950 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65  result can be de
2c960 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a  termined using.*
2c970 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2c980 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a  n_count()]..**.*
2c990 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
2c9a0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
2c9b0 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
2c9c0 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
2c9d0 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c  or if the.** col
2c9e0 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
2c9f0 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
2ca00 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
2ca10 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ed..** These rou
2ca20 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62  tines may only b
2ca30 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  e called when th
2ca40 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2ca50 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2ca60 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
2ca70 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
2ca80 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a  OW] and neither.
2ca90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2caa0 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65  t()] nor [sqlite
2cab0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61  3_finalize()] ha
2cac0 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73  ve been called s
2cad0 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
2cae0 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
2caf0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
2cb00 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
2cb10 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
2cb20 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
2cb30 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
2cb40 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2cb50 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
2cb60 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
2cb70 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
2cb80 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
2cb90 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2cba0 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
2cbb0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
2cbc0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
2cbd0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2cbe0 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
2cbf0 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
2cc00 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
2cc10 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
2cc20 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
2cc30 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
2cc40 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2cc50 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2cc60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2cc70 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ype() routine re
2cc80 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51  turns the.** [SQ
2cc90 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
2cca0 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
2ccb0 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
2ccc0 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
2ccd0 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
2cce0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
2ccf0 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
2cd00 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
2cd10 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
2cd20 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
2cd30 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
2cd40 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
2cd50 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
2cd60 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
2cd70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2cd80 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
2cd90 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
2cda0 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
2cdb0 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
2cdc0 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
2cdd0 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
2cde0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
2cdf0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
2ce00 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2ce10 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
2ce20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
2ce30 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
2ce40 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
2ce50 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
2ce60 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
2ce70 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
2ce80 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
2ce90 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
2cea0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2ceb0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
2cec0 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
2ced0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2cee0 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74  _bytes().** rout
2cef0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
2cf00 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2cf10 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
2cf20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2cf30 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
2cf40 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
2cf50 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2cf60 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
2cf70 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
2cf80 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
2cf90 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
2cfa0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
2cfb0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2cfc0 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
2cfd0 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
2cfe0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2cff0 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
2d000 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
2d010 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
2d020 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
2d030 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2d040 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
2d050 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2d060 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2d070 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
2d080 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
2d090 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2d0a0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
2d0b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2d0c0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
2d0d0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68  UTF-16 string th
2d0e0 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
2d0f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a  olumn_bytes16().
2d100 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
2d110 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2d120 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
2d130 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
2d140 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2d150 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
2d160 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
2d170 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2d180 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
2d190 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
2d1a0 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  16 and then retu
2d1b0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2d1c0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
2d1d0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2d1e0 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
2d1f0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2d200 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73  n_bytes16() uses
2d210 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
2d220 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
2d230 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
2d240 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  o a UTF-16 strin
2d250 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2d260 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2d270 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
2d280 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2d290 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
2d2a0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2d2b0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65  umn_bytes16() re
2d2c0 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
2d2d0 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65  * ^The values re
2d2e0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
2d2f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2d300 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  )] and .** [sqli
2d310 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2d320 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63  16()] do not inc
2d330 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
2d340 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65  rminators at the
2d350 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
2d360 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61  tring.  ^For cla
2d370 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73  rity: the values
2d380 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2d390 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2d3a0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71  bytes()] and [sq
2d3b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2d3c0 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20  es16()] are the 
2d3d0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
2d3e0 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
2d3f0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
2d400 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
2d410 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72  **.** ^Strings r
2d420 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2d430 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2d440 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2d450 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  umn_text16(),.**
2d460 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69   even empty stri
2d470 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20  ngs, are always 
2d480 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
2d490 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a    ^The return.**
2d4a0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
2d4b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2d4c0 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  ) for a zero-len
2d4d0 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55  gth BLOB is a NU
2d4e0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
2d4f0 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65  * ^The object re
2d500 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
2d510 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2d520 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70  )] is an.** [unp
2d530 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d540 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20  _value] object. 
2d550 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   An unprotected 
2d560 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2d570 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ject.** may only
2d580 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73   be used with [s
2d590 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2d5a0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2d5b0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
2d5c0 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e  ]..** If the [un
2d5d0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2d5e0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2d5f0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
2d600 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2d610 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20  alue()] is used 
2d620 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  in any other way
2d630 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c  , including call
2d640 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73  s.** to routines
2d650 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76   like [sqlite3_v
2d660 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
2d670 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2d680 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
2d690 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
2d6a0 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  )], then the beh
2d6b0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
2d6c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
2d6d0 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
2d6e0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
2d6f0 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
2d700 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a  opriate.  ^For.*
2d710 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  * example, if th
2d720 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
2d730 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
2d740 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
2d750 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
2d760 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
2d770 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
2d780 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
2d790 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20   perform the.** 
2d7a0 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d  conversion autom
2d7b0 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65  atically.  ^(The
2d7c0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
2d7d0 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
2d7e0 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74  versions.** that
2d7f0 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
2d800 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
2d810 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
2d820 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
2d830 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
2d840 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
2d850 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
2d860 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
2d870 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2d880 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2d890 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2d8a0 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
2d8b0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
2d8c0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
2d8d0 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
2d8e0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2d8f0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2d900 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20  td> Result is a 
2d910 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2d920 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2d930 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2d940 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2d950 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
2d960 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
2d970 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
2d980 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2d990 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
2d9a0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
2d9b0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
2d9c0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2d9d0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
2d9e0 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
2d9f0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2da00 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
2da10 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
2da20 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
2da30 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2da40 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2da50 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
2da60 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
2da70 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
2da80 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2da90 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
2daa0 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a   of the float.**
2dab0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
2dac0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
2dad0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
2dae0 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64   BLOB.** <tr><td
2daf0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
2db00 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
2db10 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
2db20 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
2db30 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
2db40 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  T    <td> [CAST]
2db50 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e   to REAL.** <tr>
2db60 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2db70 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2db80 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c  > No change.** <
2db90 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2dba0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2dbb0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
2dbc0 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
2dbd0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
2dbe0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2dbf0 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a  [CAST] to REAL.*
2dc00 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
2dc10 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
2dc20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
2dc30 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
2dc40 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
2dc50 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
2dc60 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ote>)^.**.** The
2dc70 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b   table above mak
2dc80 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20  es reference to 
2dc90 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
2dca0 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f  ry functions ato
2dcb0 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28  i().** and atof(
2dcc0 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20  ).  SQLite does 
2dcd0 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74  not really use t
2dce0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
2dcf0 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f   It has its.** o
2dd00 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e  wn equivalent in
2dd10 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e  ternal routines.
2dd20 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64    The atoi() and
2dd30 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72   atof() names ar
2dd40 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65  e.** used in the
2dd50 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69   table for brevi
2dd60 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74  ty and because t
2dd70 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72  hey are familiar
2dd80 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72   to most.** C pr
2dd90 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a  ogrammers..**.**
2dda0 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
2ddb0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
2ddc0 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
2ddd0 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
2dde0 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
2ddf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2de00 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
2de10 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
2de20 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
2de30 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
2de40 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
2de50 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
2de60 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
2de70 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
2de80 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
2de90 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
2dea0 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
2deb0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
2dec0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
2ded0 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
2dee0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2def0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
2df00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2df10 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
2df20 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
2df30 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
2df40 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
2df50 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
2df60 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
2df70 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
2df80 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
2df90 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2dfa0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
2dfb0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
2dfc0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2dfd0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
2dfe0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
2dff0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
2e000 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
2e010 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
2e020 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
2e030 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
2e040 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2e050 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
2e060 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
2e070 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
2e080 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
2e090 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
2e0a0 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
2e0b0 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
2e0c0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  ul>.**.** ^Conve
2e0d0 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
2e0e0 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
2e0f0 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
2e100 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
2e110 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
2e120 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
2e130 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
2e140 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
2e150 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
2e160 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
2e170 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66  rior pointer ref
2e180 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76  erences will hav
2e190 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
2e1a0 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
2e1b0 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
2e1c0 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
2e1d0 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
2e1e0 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
2e1f0 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
2e200 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
2e210 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
2e220 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
2e230 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
2e240 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
2e250 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20   and easiest to 
2e260 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20  remember policy 
2e270 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
2e280 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
2e290 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
2e2a0 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
2e2b0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
2e2c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2e2d0 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
2e2e0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2e2f0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
2e300 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
2e310 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
2e320 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
2e330 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
2e340 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
2e350 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2e360 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
2e370 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e380 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
2e390 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
2e3a0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
2e3b0 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
2e3c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2e3d0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
2e3e0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
2e3f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e400 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
2e410 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
2e420 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
2e430 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
2e440 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
2e450 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2e460 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
2e470 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2e480 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
2e490 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
2e4a0 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
2e4b0 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
2e4c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
2e4d0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
2e4e0 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
2e4f0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
2e500 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2e510 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
2e520 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
2e530 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2e540 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
2e550 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2e560 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
2e570 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20  * ^The pointers 
2e580 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
2e590 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
2e5a0 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
2e5b0 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
2e5c0 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
2e5d0 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
2e5e0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
2e5f0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
2e600 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2e610 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e  )] is called.  ^
2e620 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
2e630 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
2e640 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f  rings.** and BLO
2e650 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  Bs is freed auto
2e660 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c  matically.  Do <
2e670 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74  b>not</b> pass t
2e680 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
2e690 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  rned.** from [sq
2e6a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2e6b0 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  b()], [sqlite3_c
2e6c0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65  olumn_text()], e
2e6d0 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  tc. into.** [sql
2e6e0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
2e6f0 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72  .** ^(If a memor
2e700 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
2e710 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
2e720 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
2e730 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
2e740 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
2e750 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
2e760 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
2e770 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
2e780 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
2e790 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
2e7a0 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
2e7b0 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
2e7c0 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
2e7d0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
2e7e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
2e7f0 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
2e800 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
2e810 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74  MEM].)^.*/.const
2e820 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2e830 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
2e840 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2e850 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
2e860 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
2e870 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2e880 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
2e890 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2e8a0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2e8b0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75  , int iCol);.dou
2e8c0 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
2e8d0 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
2e8e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2e8f0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2e900 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
2e910 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2e920 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ol);.sqlite3_int
2e930 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
2e940 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
2e950 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2e960 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
2e970 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2e980 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
2e990 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2e9a0 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ol);.const void 
2e9b0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2e9c0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
2e9d0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2e9e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2e9f0 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
2ea00 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2ea10 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  );.sqlite3_value
2ea20 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2ea30 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
2ea40 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2ea50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ea60 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
2ea70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
2ea80 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bject.**.** ^The
2ea90 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2eaa0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
2eab0 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
2eac0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2ead0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20  tement]..** ^If 
2eae0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2eaf0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68  evaluation of th
2eb00 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f  e statement enco
2eb10 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72  untered no error
2eb20 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73  s.** or if the s
2eb30 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65  tatement is neve
2eb40 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64  r been evaluated
2eb50 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66  , then sqlite3_f
2eb60 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e  inalize() return
2eb70 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20  s.** SQLITE_OK. 
2eb80 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2eb90 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
2eba0 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66  of statement S f
2ebb0 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73  ailed, then.** s
2ebc0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2ebd0 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61  S) returns the a
2ebe0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
2ebf0 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  r code] or.** [e
2ec00 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
2ec10 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
2ec20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2ec30 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  (S) routine can 
2ec40 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
2ec50 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a   point during.**
2ec60 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20   the life cycle 
2ec70 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
2ec80 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65  tement] S:.** be
2ec90 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53  fore statement S
2eca0 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74   is ever evaluat
2ecb0 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65  ed, after.** one
2ecc0 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74   or more calls t
2ecd0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
2ece0 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e  ()], or after an
2ecf0 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71  y call.** to [sq
2ed00 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
2ed10 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
2ed20 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73  her or not the s
2ed30 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20  tatement has.** 
2ed40 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
2ed50 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f  ion..**.** ^Invo
2ed60 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e  king sqlite3_fin
2ed70 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c  alize() on a NUL
2ed80 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68  L pointer is a h
2ed90 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
2eda0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
2edb0 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69  tion must finali
2edc0 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72  ze every [prepar
2edd0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
2ede0 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a   order to avoid.
2edf0 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b  ** resource leak
2ee00 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65  s.  It is a grie
2ee10 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74  vous error for t
2ee20 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
2ee30 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20  o try to use.** 
2ee40 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
2ee50 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
2ee60 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
2ee70 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20  .  Any use of a 
2ee80 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
2ee90 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
2eea0 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
2eeb0 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20  d can result in 
2eec0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a  undefined and.**
2eed0 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68   undesirable beh
2eee0 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65  avior such as se
2eef0 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70  gfaults and heap
2ef00 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
2ef10 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
2ef20 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
2ef30 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2ef40 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
2ef50 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
2ef60 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
2ef70 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2ef80 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
2ef90 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
2efa0 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
2efb0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
2efc0 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
2efd0 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
2efe0 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
2eff0 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  xecuted..** ^Any
2f000 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
2f010 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
2f020 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
2f030 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
2f040 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
2f050 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
2f060 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
2f070 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
2f080 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
2f090 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
2f0a0 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
2f0b0 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
2f0c0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
2f0d0 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
2f0e0 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
2f0f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f100 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74  ent] S.** back t
2f110 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
2f120 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
2f130 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
2f140 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2f150 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2f160 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
2f170 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f180 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
2f190 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
2f1a0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
2f1b0 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   or if [sqlite3_
2f1c0 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76  step(S)] has nev
2f1d0 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63  er before been c
2f1e0 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74  alled on S,.** t
2f1f0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
2f200 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
2f210 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
2f220 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2f230 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2f240 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2f250 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
2f260 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2f270 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
2f280 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73  rror, then.** [s
2f290 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2f2a0 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
2f2b0 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
2f2c0 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
2f2d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2f2e0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  S)] interface do
2f2f0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
2f300 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61  e values.** of a
2f310 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ny [sqlite3_bind
2f320 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20  _blob|bindings] 
2f330 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
2f340 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
2f350 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
2f360 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
2f370 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2f380 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
2f390 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
2f3a0 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b  L Functions.** K
2f3b0 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
2f3c0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
2f3d0 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
2f3e0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
2f3f0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2f400 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
2f410 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
2f420 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2f430 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions}.**.** ^Th
2f440 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  ese functions (c
2f450 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
2f460 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
2f470 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
2f480 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
2f490 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
2f4a0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
2f4b0 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
2f4c0 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
2f4d0 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
2f4e0 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
2f4f0 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f  gregates.  The o
2f500 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20  nly differences 
2f510 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65  between.** these
2f520 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68   routines are th
2f530 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  e text encoding 
2f540 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20  expected for.** 
2f550 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
2f560 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f  eter (the name o
2f570 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62  f the function b
2f580 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a  eing created).**
2f590 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63   and the presenc
2f5a0 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20  e or absence of 
2f5b0 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  a destructor cal
2f5c0 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65  lback for.** the
2f5d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
2f5e0 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  a pointer..**.**
2f5f0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
2f600 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61  meter is the [da
2f610 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2f620 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  n] to which the 
2f630 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
2f640 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20  is to be added. 
2f650 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74   ^If an applicat
2f660 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68  ion uses more th
2f670 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a  an one database.
2f680 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
2f690 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  en application-d
2f6a0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2f6b0 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64  ions must be add
2f6c0 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61  ed.** to each da
2f6d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2f6e0 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  n separately..**
2f6f0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
2f700 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2f710 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
2f720 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2f730 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65  created or.** re
2f740 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c  defined.  ^The l
2f750 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d  ength of the nam
2f760 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20  e is limited to 
2f770 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55  255 bytes in a U
2f780 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e  TF-8.** represen
2f790 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76  tation, exclusiv
2f7a0 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65  e of the zero-te
2f7b0 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65  rminator.  ^Note
2f7c0 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a   that the name.*
2f7d0 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69  * length limit i
2f7e0 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73  s in UTF-8 bytes
2f7f0 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73  , not characters
2f800 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65   nor UTF-16 byte
2f810 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74  s.  .** ^Any att
2f820 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
2f830 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
2f840 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20   longer name.** 
2f850 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b  will result in [
2f860 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62  SQLITE_MISUSE] b
2f870 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a  eing returned..*
2f880 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
2f890 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29  parameter (nArg)
2f8a0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
2f8b0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
2f8c0 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
2f8d0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2f8e0 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20  gate takes. ^If 
2f8f0 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
2f900 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53  s -1, then the S
2f910 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
2f920 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
2f930 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
2f940 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74  of arguments bet
2f950 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c  ween 0 and the l
2f960 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b  imit.** set by [
2f970 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
2f980 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
2f990 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66  CTION_ARG]).  If
2f9a0 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
2f9b0 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
2f9c0 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
2f9d0 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e  er than 127 then
2f9e0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2f9f0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
2fa00 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
2fa10 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
2fa20 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
2fa30 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  what.** [SQLITE_
2fa40 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
2fa50 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
2fa60 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
2fa70 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
2fa80 65 74 65 72 73 2e 20 20 45 76 65 72 79 20 53 51  eters.  Every SQ
2fa90 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
2faa0 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62  mentation must b
2fab0 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a  e able to work.*
2fac0 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54  * with UTF-8, UT
2fad0 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31  F-16le, or UTF-1
2fae0 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69  6be.  But some i
2faf0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
2fb00 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66  ay be.** more ef
2fb10 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65  ficient with one
2fb20 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61   encoding than a
2fb30 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70  nother.  ^An app
2fb40 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20  lication may.** 
2fb50 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
2fb60 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2fb70 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61   or sqlite3_crea
2fb80 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20  te_function16() 
2fb90 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65  multiple.** time
2fba0 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
2fbb0 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74  function but wit
2fbc0 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75  h different valu
2fbd0 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a  es of eTextRep..
2fbe0 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c  ** ^When multipl
2fbf0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2fc00 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
2fc10 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
2fc20 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
2fc30 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
2fc40 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
2fc50 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
2fc60 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
2fc70 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65  ion..** If there
2fc80 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c   is only a singl
2fc90 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2fca0 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20   which does not 
2fcb0 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a  care what text.*
2fcc0 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  * encoding is us
2fcd0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ed, then the fou
2fce0 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rth argument sho
2fcf0 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  uld be [SQLITE_A
2fd00 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  NY]..**.** ^(The
2fd10 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
2fd20 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
2fd30 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69   pointer.  The i
2fd40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2fd50 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
2fd60 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73   can gain access
2fd70 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72   to this pointer
2fd80 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2fd90 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a  user_data()].)^.
2fda0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68  **.** ^The sixth
2fdb0 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69  , seventh and ei
2fdc0 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c  ghth parameters,
2fdd0 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e   xFunc, xStep an
2fde0 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a  d xFinal, are.**
2fdf0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c   pointers to C-l
2fe00 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e  anguage function
2fe10 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
2fe20 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2fe30 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2fe40 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c  e. ^A scalar SQL
2fe50 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
2fe60 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
2fe70 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e  tion of the xFun
2fe80 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e  c.** callback on
2fe90 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ly; NULL pointer
2fea0 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  s must be passed
2feb0 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e   as the xStep an
2fec0 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61  d xFinal.** para
2fed0 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72  meters. ^An aggr
2fee0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2fef0 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
2ff00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2ff10 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46   xStep.** and xF
2ff20 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f  inal and NULL po
2ff30 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61  inter must be pa
2ff40 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20  ssed for xFunc. 
2ff50 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78  ^To delete an ex
2ff60 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75  isting.** SQL fu
2ff70 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
2ff80 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70  ate, pass NULL p
2ff90 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20  ointers for all 
2ffa0 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  three function.*
2ffb0 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a  * callbacks..**.
2ffc0 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74  ** ^(If the nint
2ffd0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2ffe0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2fff0 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e  nction_v2() is n
30000 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e  ot NULL,.** then
30010 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f   it is destructo
30020 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63  r for the applic
30030 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
30040 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74  er. .** The dest
30050 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65  ructor is invoke
30060 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74  d when the funct
30070 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20  ion is deleted, 
30080 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a  either by being.
30090 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72  ** overloaded or
300a0 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
300b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
300c0 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20  oses.)^.** ^The 
300d0 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c  destructor is al
300e0 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68  so invoked if th
300f0 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  e call to.** sql
30100 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
30110 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e  tion_v2() fails.
30120 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65  .** ^When the de
30130 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
30140 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70  k of the tenth p
30150 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f  arameter is invo
30160 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61  ked, it.** is pa
30170 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72  ssed a single ar
30180 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
30190 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70  a copy of the ap
301a0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a  plication data .
301b0 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  ** pointer which
301c0 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70   was the fifth p
301d0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
301e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
301f0 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  ion_v2()..**.** 
30200 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64  ^It is permitted
30210 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c   to register mul
30220 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
30230 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
30240 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77  e.** functions w
30250 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
30260 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65  e but with eithe
30270 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62  r differing numb
30280 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65  ers of.** argume
30290 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67  nts or differing
302a0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
302b0 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c  encodings.  ^SQL
302c0 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
302d0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
302e0 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f  on that most clo
302f0 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65  sely matches the
30300 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68   way in which th
30310 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  e.** SQL functio
30320 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66  n is used.  ^A f
30330 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
30340 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
30350 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41  n-negative.** nA
30360 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rg parameter is 
30370 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74  a better match t
30380 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69  han a function i
30390 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
303a0 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65  th.** a negative
303b0 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74   nArg.  ^A funct
303c0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72  ion where the pr
303d0 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
303e0 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73  oding.** matches
303f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
30400 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74  coding is a bett
30410 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e  er.** match than
30420 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
30430 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69  e the encoding i
30440 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a  s different.  .*
30450 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68  * ^A function wh
30460 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
30470 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62   difference is b
30480 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61  etween UTF16le a
30490 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73  nd UTF16be.** is
304a0 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20   a closer match 
304b0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
304c0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
304d0 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
304e0 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38  .** between UTF8
304f0 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a   and UTF16..**.*
30500 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63  * ^Built-in func
30510 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65  tions may be ove
30520 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61  rloaded by new a
30530 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
30540 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  ed functions..**
30550 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74  .** ^An applicat
30560 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
30570 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
30580 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a  d to call other.
30590 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
305a0 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20  aces.  However, 
305b0 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20  such calls must 
305c0 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65  not.** close the
305d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
305e0 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a  tion nor finaliz
305f0 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70  e or reset the p
30600 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
30610 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68  ment in which th
30620 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  e function is ru
30630 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nning..*/.int sq
30640 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30650 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
30660 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
30670 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
30680 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
30690 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
306a0 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
306b0 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
306c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
306d0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
306e0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
306f0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
30700 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
30710 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
30720 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
30730 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
30740 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
30750 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
30760 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
30770 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
30780 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
30790 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
307a0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
307b0 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
307c0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
307d0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
307e0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
307f0 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
30800 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
30810 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
30820 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
30830 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
30840 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
30850 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30860 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ction_v2(.  sqli
30870 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
30880 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
30890 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
308a0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
308b0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
308c0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
308d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
308e0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
308f0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
30900 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
30910 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
30920 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
30930 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
30940 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
30950 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
30960 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  oy)(void*).);../
30970 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
30980 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a  ext Encodings.**
30990 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
309a0 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65  nt define intege
309b0 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70  r codes that rep
309c0 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f  resent the vario
309d0 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  us.** text encod
309e0 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62  ings supported b
309f0 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  y SQLite..*/.#de
30a00 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38  fine SQLITE_UTF8
30a10 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
30a20 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
30a30 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65  6LE        2.#de
30a40 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
30a50 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65  6BE        3.#de
30a60 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
30a70 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20  6          4    
30a80 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79  /* Use native by
30a90 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66  te order */.#def
30aa0 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20  ine SQLITE_ANY  
30ab0 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f            5    /
30ac0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
30ad0 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a  _function only *
30ae0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
30af0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20  _UTF16_ALIGNED  
30b00 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  8    /* sqlite3_
30b10 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
30b20 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   only */../*.** 
30b30 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63  CAPI3REF: Deprec
30b40 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ated Functions.*
30b50 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a  * DEPRECATED.**.
30b60 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
30b70 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74  ns are [deprecat
30b80 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74  ed].  In order t
30b90 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61  o maintain.** ba
30ba0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
30bb0 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72  ility with older
30bc0 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e   code, these fun
30bd0 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
30be0 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72  .** to be suppor
30bf0 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ted.  However, n
30c00 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
30c10 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20  should avoid.** 
30c20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65  the use of these
30c30 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20   functions.  To 
30c40 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70  help encourage p
30c50 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a  eople to avoid.*
30c60 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75  * using these fu
30c70 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20  nctions, we are 
30c80 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c  not going to tel
30c90 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20  l you what they 
30ca0 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  do..*/.#ifndef S
30cb0 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45  QLITE_OMIT_DEPRE
30cc0 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50  CATED.SQLITE_DEP
30cd0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
30ce0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
30cf0 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  unt(sqlite3_cont
30d00 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  ext*);.SQLITE_DE
30d10 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
30d20 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c  ite3_expired(sql
30d30 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
30d40 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
30d50 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73  nt sqlite3_trans
30d60 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  fer_bindings(sql
30d70 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69  ite3_stmt*, sqli
30d80 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
30d90 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
30da0 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
30db0 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
30dc0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
30dd0 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74  D void sqlite3_t
30de0 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f  hread_cleanup(vo
30df0 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  id);.SQLITE_DEPR
30e00 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
30e10 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28  e3_memory_alarm(
30e20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
30e30 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29  lite3_int64,int)
30e40 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
30e50 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71          void*,sq
30e60 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65  lite3_int64);.#e
30e70 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
30e80 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20  3REF: Obtaining 
30e90 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72  SQL Function Par
30ea0 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a  ameter Values.**
30eb0 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61  .** The C-langua
30ec0 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ge implementatio
30ed0 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f  n of SQL functio
30ee0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
30ef0 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73  s uses.** this s
30f00 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20  et of interface 
30f10 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65  routines to acce
30f20 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ss the parameter
30f30 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68   values on.** th
30f40 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  e function or ag
30f50 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54  gregate..**.** T
30f60 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63  he xFunc (for sc
30f70 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20  alar functions) 
30f80 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67  or xStep (for ag
30f90 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65  gregates) parame
30fa0 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ters.** to [sqli
30fb0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
30fc0 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
30fd0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
30fe0 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69  ion16()].** defi
30ff0 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  ne callbacks tha
31000 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
31010 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
31020 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a  d aggregates..**
31030 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   The 3rd paramet
31040 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c  er to these call
31050 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61  backs is an arra
31060 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
31070 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73  .** [protected s
31080 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
31090 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73  jects.  There is
310a0 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   one [sqlite3_va
310b0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a  lue] object for.
310c0 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65  ** each paramete
310d0 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  r to the SQL fun
310e0 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f  ction.  These ro
310f0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
31100 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61  to.** extract va
31110 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73  lues from the [s
31120 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
31130 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  jects..**.** The
31140 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
31150 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74   only with [prot
31160 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
31170 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
31180 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
31190 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  use these routin
311a0 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74  es on an [unprot
311b0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
311c0 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  lue].** object r
311d0 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
311e0 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
311f0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
31200 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
31210 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
31220 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63  ding [column acc
31230 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a  ess functions].*
31240 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74  * except that  t
31250 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61  hese routines ta
31260 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f  ke a single [pro
31270 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
31280 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
31290 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20  pointer instead 
312a0 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  of a [sqlite3_st
312b0 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
312c0 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
312d0 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
312e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
312f0 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74  lue_text16() int
31300 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20  erface extracts 
31310 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a  a UTF-16 string.
31320 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
31330 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74   byte-order of t
31340 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e  he host machine.
31350 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
31360 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
31370 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
31380 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20  alue_text16le() 
31390 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78  interfaces.** ex
313a0 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72  tract UTF-16 str
313b0 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69  ings as big-endi
313c0 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e  an and little-en
313d0 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
313e0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  y..**.** ^(The s
313f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
31400 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
31410 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
31420 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
31430 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
31440 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
31450 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
31460 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
31470 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
31480 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
31490 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
314a0 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
314b0 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
314c0 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
314d0 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
314e0 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
314f0 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74  r.** words, if t
31500 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74  he value is a st
31510 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20  ring that looks 
31520 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a  like a number).*
31530 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65  * then the conve
31540 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
31550 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e  ed.  Otherwise n
31560 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  o conversion occ
31570 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  urs..** The [SQL
31580 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
31590 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
315a0 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
315b0 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c  rned.)^.**.** Pl
315c0 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75  ease pay particu
315d0 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f  lar attention to
315e0 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74   the fact that t
315f0 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72  he pointer retur
31600 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
31610 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
31620 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
31630 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a  ue_text()], or.*
31640 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
31650 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62  _text16()] can b
31660 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79  e invalidated by
31670 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   a subsequent ca
31680 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
31690 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
316a0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
316b0 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71  _bytes16()], [sq
316c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
316d0 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
316e0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
316f0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ()]..**.** These
31700 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
31710 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
31720 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73  e same thread as
31730 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
31740 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69  tion that suppli
31750 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ed the [sqlite3_
31760 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65  value*] paramete
31770 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  rs..*/.const voi
31780 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
31790 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
317a0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
317b0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
317c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
317d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
317e0 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
317f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c  3_value*);.doubl
31800 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
31810 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76  double(sqlite3_v
31820 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
31830 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
31840 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73  lite3_value*);.s
31850 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
31860 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
31870 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
31880 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
31890 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
318a0 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
318b0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
318c0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
318d0 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69  alue_text16(sqli
318e0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
318f0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
31900 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
31910 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
31920 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
31930 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
31940 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6be(sqlite3_valu
31950 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
31960 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(sqli
31970 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
31980 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
31990 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
319a0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
319b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
319c0 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
319d0 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a  unction Context.
319e0 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61  **.** Implementa
319f0 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61  tions of aggrega
31a00 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  te SQL functions
31a10 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75   use this.** rou
31a20 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  tine to allocate
31a30 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72   memory for stor
31a40 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e  ing their state.
31a50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
31a60 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74  t time the sqlit
31a70 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
31a80 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
31a90 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20  e is called .** 
31aa0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
31ab0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
31ac0 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ion, SQLite.** a
31ad0 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65  llocates N of me
31ae0 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74  mory, zeroes out
31af0 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e   that memory, an
31b00 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
31b10 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65  ter.** to the ne
31b20 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65  w memory. ^On se
31b30 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
31b40 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ent calls to.** 
31b50 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
31b60 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20  e_context() for 
31b70 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
31b80 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
31b90 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d  ance,.** the sam
31ba0 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75  e buffer is retu
31bb0 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61  rned.  Sqlite3_a
31bc0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
31bd0 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a  () is normally.*
31be0 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f  * called once fo
31bf0 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  r each invocatio
31c00 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63  n of the xStep c
31c10 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e  allback and then
31c20 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d   one.** last tim
31c30 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61  e when the xFina
31c40 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  l callback is in
31c50 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e  voked.  ^(When n
31c60 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20  o rows match.** 
31c70 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65  an aggregate que
31c80 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20  ry, the xStep() 
31c90 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
31ca0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
31cb0 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  on.** implementa
31cc0 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61  tion is never ca
31cd0 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28  lled and xFinal(
31ce0 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63  ) is called exac
31cf0 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20  tly once..** In 
31d00 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c  those cases, sql
31d10 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
31d20 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62  ontext() might b
31d30 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65  e called for the
31d40 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66  .** first time f
31d50 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61  rom within xFina
31d60 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  l().)^.**.** ^Th
31d70 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
31d80 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
31d90 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
31da0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
31db0 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63  .** when first c
31dc0 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65  alled if N is le
31dd0 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
31de0 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61   to zero or if a
31df0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
31e00 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ate error occurs
31e10 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d  ..**.** ^(The am
31e20 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c  ount of space al
31e30 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
31e40 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
31e50 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20  text(C,N) is.** 
31e60 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68  determined by th
31e70 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  e N parameter on
31e80 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75   first successfu
31e90 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e  l call.  Changin
31ea0 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  g the.** value o
31eb0 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e  f N in subsequen
31ec0 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
31ed0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
31ee0 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20  ext() within.** 
31ef0 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
31f00 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
31f10 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65  ance will not re
31f20 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a  size the memory.
31f30 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e  ** allocation.)^
31f40 20 20 57 69 74 68 69 6e 20 74 68 65 20 78 46 69    Within the xFi
31f50 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74  nal callback, it
31f60 20 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f   is customary to
31f70 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63   set.** N=0 in c
31f80 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
31f90 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
31fa0 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e  t(C,N) so that n
31fb0 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20  o .** pointless 
31fc0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
31fd0 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20  ns occur..**.** 
31fe0 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69  ^SQLite automati
31ff0 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
32000 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64  memory allocated
32010 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   by .** sqlite3_
32020 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
32030 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67  t() when the agg
32040 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e  regate query con
32050 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
32060 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
32070 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79  r must be a copy
32080 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
32090 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51  te3_context | SQ
320a0 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65  L function conte
320b0 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20  xt] that is the 
320c0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a  first parameter.
320d0 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20  ** to the xStep 
320e0 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
320f0 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20  ck routine that 
32100 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61  implements the a
32110 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63  ggregate.** func
32120 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
32130 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
32140 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
32150 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
32160 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67  which.** the agg
32170 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
32180 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
32190 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
321a0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
321b0 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
321c0 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29  xt*, int nBytes)
321d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
321e0 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72  F: User Data For
321f0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
32200 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73   ^The sqlite3_us
32210 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66  er_data() interf
32220 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
32230 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
32240 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68  nter that was th
32250 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61  e pUserData para
32260 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70  meter (the 5th p
32270 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
32280 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
32290 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
322a0 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
322b0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
322c0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
322d0 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
322e0 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
322f0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
32300 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ned function..**
32310 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
32320 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
32330 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
32340 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
32350 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
32360 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
32370 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
32380 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75  .void *sqlite3_u
32390 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33  ser_data(sqlite3
323a0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
323b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
323c0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
323d0 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
323e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
323f0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
32400 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  dle() interface 
32410 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
32420 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
32430 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
32440 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74  e connection] (t
32450 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
32460 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
32470 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
32480 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
32490 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
324a0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
324b0 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
324c0 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
324d0 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
324e0 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
324f0 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  tion..*/.sqlite3
32500 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   *sqlite3_contex
32510 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  t_db_handle(sqli
32520 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
32530 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32540 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61  Function Auxilia
32550 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68  ry Data.**.** Th
32560 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  ese functions ma
32570 79 20 62 65 20 75 73 65 64 20 62 79 20 28 6e 6f  y be used by (no
32580 6e 2d 61 67 67 72 65 67 61 74 65 29 20 53 51 4c  n-aggregate) SQL
32590 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a   functions to.**
325a0 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64   associate metad
325b0 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ata with argumen
325c0 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65  t values. If the
325d0 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70   same value is p
325e0 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74  assed to.** mult
325f0 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73  iple invocations
32600 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c   of the same SQL
32610 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67   function during
32620 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e   query execution
32630 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20  , under.** some 
32640 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68  circumstances th
32650 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74  e associated met
32660 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65  adata may be pre
32670 73 65 72 76 65 64 2e 20 20 41 6e 20 65 78 61 6d  served.  An exam
32680 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20  ple.** of where 
32690 74 68 69 73 20 6d 69 67 68 74 20 62 65 20 75 73  this might be us
326a0 65 66 75 6c 20 69 73 20 69 6e 20 61 20 72 65 67  eful is in a reg
326b0 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20  ular-expression 
326c0 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63  matching.** func
326d0 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c  tion. The compil
326e0 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ed version of th
326f0 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
32700 73 69 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f 72  sion can be stor
32710 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74  ed as.** metadat
32720 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
32730 68 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74  h the pattern st
32740 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20  ring.  .** Then 
32750 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 70  as long as the p
32760 61 74 74 65 72 6e 20 73 74 72 69 6e 67 20 72 65  attern string re
32770 6d 61 69 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a  mains the same,.
32780 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20  ** the compiled 
32790 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
327a0 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64  on can be reused
327b0 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20   on multiple.** 
327c0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
327d0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
327e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
327f0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
32800 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
32810 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
32820 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a  o the metadata.*
32830 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20  * associated by 
32840 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
32850 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69  auxdata() functi
32860 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20  on with the Nth 
32870 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75  argument.** valu
32880 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  e to the applica
32890 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
328a0 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65  ction. ^If there
328b0 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a   is no metadata.
328c0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
328d0 74 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  th the function 
328e0 61 72 67 75 6d 65 6e 74 2c 20 74 68 69 73 20 73  argument, this s
328f0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
32900 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  ta() interface.*
32910 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  * returns a NULL
32920 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
32930 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74  ^The sqlite3_set
32940 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
32950 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65  ) interface save
32960 73 20 50 20 61 73 20 6d 65 74 61 64 61 74 61 20  s P as metadata 
32970 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20  for the N-th.** 
32980 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
32990 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
329a0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e  ned function.  ^
329b0 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  Subsequent.** ca
329c0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67  lls to sqlite3_g
329d0 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 20  et_auxdata(C,N) 
329e0 72 65 74 75 72 6e 20 50 20 66 72 6f 6d 20 74 68  return P from th
329f0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a  e most recent.**
32a00 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
32a10 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61  data(C,N,P,X) ca
32a20 6c 6c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61  ll if the metada
32a30 74 61 20 69 73 20 73 74 69 6c 6c 20 76 61 6c 69  ta is still vali
32a40 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20  d or.** NULL if 
32a50 74 68 65 20 6d 65 74 61 64 61 74 61 20 68 61 73  the metadata has
32a60 20 62 65 65 6e 20 64 69 73 63 61 72 64 65 64 2e   been discarded.
32a70 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61 63 68 20  .** ^After each 
32a80 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
32a90 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
32aa0 50 2c 58 29 20 77 68 65 72 65 20 58 20 69 73 20  P,X) where X is 
32ab0 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c  not NULL,.** SQL
32ac0 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  ite will invoke 
32ad0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 66  the destructor f
32ae0 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 20 70  unction X with p
32af0 61 72 61 6d 65 74 65 72 20 50 20 65 78 61 63 74  arameter P exact
32b00 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e  ly.** once, when
32b10 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73   the metadata is
32b20 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53   discarded..** S
32b30 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f  QLite is free to
32b40 20 64 69 73 63 61 72 64 20 74 68 65 20 6d 65 74   discard the met
32b50 61 64 61 74 61 20 61 74 20 61 6e 79 20 74 69 6d  adata at any tim
32b60 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75  e, including: <u
32b70 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20  l>.** <li> when 
32b80 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
32b90 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
32ba0 65 74 65 72 20 63 68 61 6e 67 65 73 2c 20 6f 72  eter changes, or
32bb0 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73  .** <li> when [s
32bc0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
32bd0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
32be0 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
32bf0 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  d for the.**    
32c00 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c    SQL statement,
32c10 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e   or.** <li> when
32c20 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
32c30 64 61 74 61 28 29 20 69 73 20 69 6e 76 6f 6b 65  data() is invoke
32c40 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 65 20 73  d again on the s
32c50 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 6f  ame parameter, o
32c60 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67  r.** <li> during
32c70 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 71   the original sq
32c80 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
32c90 61 28 29 20 63 61 6c 6c 20 77 68 65 6e 20 61 20  a() call when a 
32ca0 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20  memory .**      
32cb0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
32cc0 20 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e   occurs. </ul>)^
32cd0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20  .**.** Note the 
32ce0 6c 61 73 74 20 62 75 6c 6c 65 74 20 69 6e 20 70  last bullet in p
32cf0 61 72 74 69 63 75 6c 61 72 2e 20 20 54 68 65 20  articular.  The 
32d00 64 65 73 74 72 75 63 74 6f 72 20 58 20 69 6e 20  destructor X in 
32d10 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  .** sqlite3_set_
32d20 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
32d30 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64   might be called
32d40 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
32d50 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69  fore the.** sqli
32d60 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
32d70 29 20 69 6e 74 65 72 66 61 63 65 20 65 76 65 6e  ) interface even
32d80 20 72 65 74 75 72 6e 73 2e 20 20 48 65 6e 63 65   returns.  Hence
32d90 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
32da0 64 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c 64  data().** should
32db0 20 62 65 20 63 61 6c 6c 65 64 20 6e 65 61 72 20   be called near 
32dc0 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
32dd0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
32de0 74 61 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a 2a  tation and the.*
32df0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  * function imple
32e00 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
32e10 20 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75 73   not make any us
32e20 65 20 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a 20  e of P after.** 
32e30 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
32e40 61 74 61 28 29 20 68 61 73 20 62 65 65 6e 20 63  ata() has been c
32e50 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  alled..**.** ^(I
32e60 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61  n practice, meta
32e70 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65  data is preserve
32e80 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69  d between functi
32e90 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20  on calls for.** 
32ea0 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
32eb0 65 72 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d  ers that are com
32ec0 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74 61  pile-time consta
32ed0 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6c  nts, including l
32ee0 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
32ef0 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73   and [parameters
32f00 5d 20 61 6e 64 20 65 78 70 72 65 73 73 69 6f 6e  ] and expression
32f10 73 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20  s composed from 
32f20 74 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a  the same.)^.**.*
32f30 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
32f40 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
32f50 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
32f60 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
32f70 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
32f80 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
32f90 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67  .void *sqlite3_g
32fa0 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
32fb0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
32fc0 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65   N);.void sqlite
32fd0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_set_auxdata(sq
32fe0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
32ff0 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f  int N, void*, vo
33000 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  id (*)(void*));.
33010 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33020 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69  : Constants Defi
33030 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73  ning Special Des
33040 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72  tructor Behavior
33050 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
33060 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20   special values 
33070 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74  for the destruct
33080 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  or that is passe
33090 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66  d in as the.** f
330a0 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f  inal argument to
330b0 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
330c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
330d0 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  lob()].  ^If the
330e0 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61   destructor.** a
330f0 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54  rgument is SQLIT
33100 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61  E_STATIC, it mea
33110 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
33120 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63  ent pointer is c
33130 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77  onstant.** and w
33140 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65  ill never change
33150 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e  .  It does not n
33160 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f  eed to be destro
33170 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51  yed.  ^The.** SQ
33180 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76  LITE_TRANSIENT v
33190 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20  alue means that 
331a0 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c  the content will
331b0 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69   likely change i
331c0 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75  n.** the near fu
331d0 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51  ture and that SQ
331e0 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65  Lite should make
331f0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
33200 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
33210 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72  content before r
33220 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
33230 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e  The typedef is n
33240 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b  ecessary to work
33250 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73   around problems
33260 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43   in certain.** C
33270 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f  ++ compilers..*/
33280 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
33290 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
332a0 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b  or_type)(void*);
332b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
332c0 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71  STATIC      ((sq
332d0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
332e0 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65  _type)0).#define
332f0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
33300 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65  T   ((sqlite3_de
33310 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31  structor_type)-1
33320 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
33330 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52  F: Setting The R
33340 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20  esult Of An SQL 
33350 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54  Function.**.** T
33360 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
33370 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46  e used by the xF
33380 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  unc or xFinal ca
33390 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20  llbacks that.** 
333a0 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75  implement SQL fu
333b0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
333c0 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20  egates.  See.** 
333d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
333e0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
333f0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
33400 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
33410 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
33420 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
33430 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
33440 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63  ns work very muc
33450 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61  h like the [para
33460 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66  meter binding] f
33470 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63  amily of.** func
33480 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69  tions used to bi
33490 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
334a0 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  t parameters in 
334b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
334c0 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f  nts..** Refer to
334d0 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65   the [SQL parame
334e0 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  ter] documentati
334f0 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  on for additiona
33500 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
33510 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
33520 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20  3_result_blob() 
33530 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
33540 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
33550 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
33560 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
33570 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42  n to be the BLOB
33580 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69   whose content i
33590 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20  s pointed.** to 
335a0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  by the second pa
335b0 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63  rameter and whic
335c0 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e  h is N bytes lon
335d0 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  g where N is the
335e0 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
335f0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
33600 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
33610 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  eroblob() interf
33620 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73  aces set the res
33630 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
33640 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
33650 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
33660 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69   a BLOB containi
33670 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62  ng all zero.** b
33680 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73  ytes and N bytes
33690 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20   in size, where 
336a0 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  N is the value o
336b0 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
336c0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
336d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
336e0 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  ouble() interfac
336f0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
33700 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
33710 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
33720 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
33730 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
33740 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
33750 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61  .** by its 2nd a
33760 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
33770 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
33780 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
33790 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
337a0 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e  ror16() function
337b0 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69  s.** cause the i
337c0 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66  mplemented SQL f
337d0 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77  unction to throw
337e0 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a   an exception..*
337f0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
33800 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  he string pointe
33810 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32  d to by the.** 2
33820 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
33830 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33840 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65  rror() or sqlite
33850 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
33860 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78  ().** as the tex
33870 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65  t of an error me
33880 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20  ssage.  ^SQLite 
33890 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65  interprets the e
338a0 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
338b0 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
338c0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
338d0 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51  () as UTF-8. ^SQ
338e0 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  Lite.** interpre
338f0 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72  ts the string fr
33900 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
33910 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55  t_error16() as U
33920 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a  TF-16 in native.
33930 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20  ** byte order.  
33940 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
33950 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
33960 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
33970 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
33980 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
33990 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65   is negative the
339a0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61  n SQLite takes a
339b0 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
339c0 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20  essage all text 
339d0 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  up through the f
339e0 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
339f0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
33a00 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
33a10 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
33a20 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20  t_error() or.** 
33a30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33a40 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d  rror16() is non-
33a50 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
33a60 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20  Lite takes that 
33a70 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e  many.** bytes (n
33a80 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66  ot characters) f
33a90 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
33aa0 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72  meter as the err
33ab0 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e  or message..** ^
33ac0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
33ad0 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
33ae0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33af0 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  ror16().** routi
33b00 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61  nes make a priva
33b10 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65  te copy of the e
33b20 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
33b30 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79  t before.** they
33b40 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c   return.  Hence,
33b50 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
33b60 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f  ction can deallo
33b70 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66  cate or.** modif
33b80 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72  y the text after
33b90 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74   they return wit
33ba0 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54  hout harm..** ^T
33bb0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33bc0 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66  t_error_code() f
33bd0 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20  unction changes 
33be0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  the error code.*
33bf0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  * returned by SQ
33c00 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74  Lite as a result
33c10 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20   of an error in 
33c20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79  a function.  ^By
33c30 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65   default,.** the
33c40 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53   error code is S
33c50 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41  QLITE_ERROR.  ^A
33c60 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
33c70 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
33c80 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
33c90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33ca0 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73  error16() resets
33cb0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
33cc0 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  to SQLITE_ERROR.
33cd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
33ce0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33cf0 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66  _toobig() interf
33d00 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
33d10 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a  e to throw an.**
33d20 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e   error indicatin
33d30 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20  g that a string 
33d40 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c  or BLOB is too l
33d50 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ong to represent
33d60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
33d70 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33d80 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66  r_nomem() interf
33d90 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
33da0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a  e to throw an.**
33db0 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e   error indicatin
33dc0 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20  g that a memory 
33dd0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65  allocation faile
33de0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
33df0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
33e00 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
33e10 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
33e20 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
33e30 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
33e40 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
33e50 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65  the 32-bit signe
33e60 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
33e70 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
33e80 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
33e90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
33ea0 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74  sult_int64() int
33eb0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
33ec0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
33ed0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
33ee0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
33ef0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34  ion to be the 64
33f00 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
33f10 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
33f20 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
33f30 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
33f40 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33f50 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61  t_null() interfa
33f60 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
33f70 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
33f80 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
33f90 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
33fa0 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
33fb0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
33fc0 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71  esult_text(), sq
33fd0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
33fe0 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  t16(),.** sqlite
33ff0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
34000 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  e(), and sqlite3
34010 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
34020 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
34030 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20   set the return 
34040 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70  value of the app
34050 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
34060 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a   function to be.
34070 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  ** a text string
34080 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73   which is repres
34090 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20  ented as UTF-8, 
340a0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
340b0 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46  te order,.** UTF
340c0 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61  -16 little endia
340d0 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
340e0 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74   endian, respect
340f0 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ively..** ^SQLit
34100 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74  e takes the text
34110 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65   result from the
34120 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f   application fro
34130 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72  m.** the 2nd par
34140 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71  ameter of the sq
34150 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
34160 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  t* interfaces..*
34170 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
34180 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
34190 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
341a0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
341b0 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
341c0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
341d0 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f   result text fro
341e0 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
341f0 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74  ter.** through t
34200 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
34210 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
34220 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
34230 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
34240 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
34250 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
34260 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
34270 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20  n as many bytes 
34280 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
34290 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20   of the text.** 
342a0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
342b0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
342c0 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65  are taken as the
342d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
342e0 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ined.** function
342f0 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65   result.  If the
34300 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69   3rd parameter i
34310 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
34320 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20  then it.** must 
34330 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
34340 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69  et into the stri
34350 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c  ng where the NUL
34360 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c   terminator woul
34370 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74  d.** appear if t
34380 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20  he string where 
34390 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  NUL terminated. 
343a0 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
343b0 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20  acters occur.** 
343c0 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61 74  in the string at
343d0 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 20 74   a byte offset t
343e0 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  hat is less than
343f0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
34400 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  e 3rd.** paramet
34410 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  er, then the res
34420 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69  ulting string wi
34430 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ll contain embed
34440 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65  ded NULs and the
34450 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78  .** result of ex
34460 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74  pressions operat
34470 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77  ing on strings w
34480 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
34490 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
344a0 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
344b0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
344c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
344d0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
344e0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
344f0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e  sult_blob is a n
34500 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
34510 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c   then SQLite cal
34520 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74  ls that.** funct
34530 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72  ion as the destr
34540 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78  uctor on the tex
34550 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
34560 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
34570 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
34580 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
34590 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
345a0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
345b0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
345c0 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74   interfaces or t
345d0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  o.** sqlite3_res
345e0 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
345f0 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
34600 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
34610 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  then SQLite.** a
34620 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20  ssumes that the 
34630 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
34640 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61  ult is in consta
34650 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  nt space and doe
34660 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68  s not.** copy th
34670 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
34680 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63   parameter nor c
34690 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72  all a destructor
346a0 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a   on the content.
346b0 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66  ** when it has f
346c0 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
346d0 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
346e0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
346f0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
34700 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
34710 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
34720 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34730 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
34740 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
34750 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a  ITE_TRANSIENT.**
34760 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b   then SQLite mak
34770 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
34780 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61   result into spa
34790 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ce obtained from
347a0 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
347b0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f  3_malloc()] befo
347c0 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a  re it returns..*
347d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
347e0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
347f0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
34800 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
34810 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34820 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
34830 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74  n to be a copy t
34840 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  he.** [unprotect
34850 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
34860 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  ] object specifi
34870 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  ed by the 2nd pa
34880 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a  rameter.  ^The.*
34890 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
348a0 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
348b0 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
348c0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
348d0 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61  value].** so tha
348e0 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  t the [sqlite3_v
348f0 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20  alue] specified 
34900 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
34910 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a   may change or.*
34920 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  * be deallocated
34930 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72   after sqlite3_r
34940 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65  esult_value() re
34950 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61  turns without ha
34960 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65  rm..** ^A [prote
34970 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
34980 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61  ue] object may a
34990 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68  lways be used wh
349a0 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f  ere an.** [unpro
349b0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
349c0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20  alue] object is 
349d0 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74  required, so eit
349e0 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b  her.** kind of [
349f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
34a00 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65  bject can be use
34a10 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65  d with this inte
34a20 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rface..**.** If 
34a30 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
34a40 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77  re called from w
34a50 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72  ithin the differ
34a60 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68  ent thread.** th
34a70 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61  an the one conta
34a80 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63  ining the applic
34a90 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
34aa0 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65  nction that rece
34ab0 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  ived.** the [sql
34ac0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f  ite3_context] po
34ad0 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c  inter, the resul
34ae0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
34af0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
34b00 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71  3_result_blob(sq
34b10 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
34b20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
34b30 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
34b40 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
34b50 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71  result_double(sq
34b60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
34b70 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71  double);.void sq
34b80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
34b90 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  or(sqlite3_conte
34ba0 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
34bb0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
34bc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34bd0 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r16(sqlite3_cont
34be0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
34bf0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
34c00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
34c10 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65  or_toobig(sqlite
34c20 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
34c30 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34c40 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c  _error_nomem(sql
34c50 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
34c60 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
34c70 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73  ult_error_code(s
34c80 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
34c90 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
34ca0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73  te3_result_int(s
34cb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
34cc0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
34cd0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
34ce0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
34cf0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
34d00 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
34d10 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69  result_null(sqli
34d20 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
34d30 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
34d40 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  lt_text(sqlite3_
34d50 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
34d60 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  char*, int, void
34d70 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
34d80 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34d90 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
34da0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
34db0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
34dc0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
34dd0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34de0 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
34df0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
34e00 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
34e10 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
34e20 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
34e30 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  t_text16be(sqlit
34e40 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
34e50 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
34e60 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
34e70 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
34e80 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  lt_value(sqlite3
34e90 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
34ea0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64  e3_value*);.void
34eb0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34ec0 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
34ed0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
34ee0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34ef0 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43  EF: Define New C
34f00 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63  ollating Sequenc
34f10 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  es.**.** ^These 
34f20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72  functions add, r
34f30 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79  emove, or modify
34f40 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61   a [collation] a
34f50 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74  ssociated.** wit
34f60 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
34f70 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
34f80 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
34f90 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
34fa0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
34fb0 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  the collation is
34fc0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a   a UTF-8 string.
34fd0 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
34fe0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
34ff0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72  ) and sqlite3_cr
35000 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
35010 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46  2().** and a UTF
35020 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
35030 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
35040 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
35050 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
35060 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20  ..** ^Collation 
35070 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61  names that compa
35080 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69  re equal accordi
35090 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ng to [sqlite3_s
350a0 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a  trnicmp()] are.*
350b0 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20  * considered to 
350c0 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  be the same name
350d0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68  ..**.** ^(The th
350e0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54  ird argument (eT
350f0 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20  extRep) must be 
35100 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
35110 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ants:.** <ul>.**
35120 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
35130 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  F8],.** <li> [SQ
35140 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a  LITE_UTF16LE],.*
35150 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
35160 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  TF16BE],.** <li>
35170 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c   [SQLITE_UTF16],
35180 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
35190 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
351a0 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  D]..** </ul>)^.*
351b0 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20  * ^The eTextRep 
351c0 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69  argument determi
351d0 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  nes the encoding
351e0 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73   of strings pass
351f0 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c  ed.** to the col
35200 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
35210 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62  callback, xCallb
35220 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ack..** ^The [SQ
35230 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20  LITE_UTF16] and 
35240 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
35250 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f  IGNED] values fo
35260 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f  r eTextRep.** fo
35270 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62  rce strings to b
35280 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74  e UTF16 with nat
35290 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
352a0 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
352b0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76  UTF16_ALIGNED] v
352c0 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65  alue for eTextRe
352d0 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73  p forces strings
352e0 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20   to begin.** on 
352f0 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64  an even byte add
35300 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ress..**.** ^The
35310 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
35320 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70  , pArg, is an ap
35330 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
35340 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70  ointer that is p
35350 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68  assed.** through
35360 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
35370 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f  gument to the co
35380 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
35390 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
353a0 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
353b0 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c  ment, xCallback,
353c0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
353d0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
353e0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c  unction..** ^Mul
353f0 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20  tiple collating 
35400 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65  functions can be
35410 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
35420 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
35430 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66  but.** with diff
35440 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 70  erent eTextRep p
35450 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51  arameters and SQ
35460 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68  Lite will use wh
35470 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74  ichever.** funct
35480 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68 65  ion requires the
35490 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
354a0 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61   data transforma
354b0 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  tion..** ^If the
354c0 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d   xCallback argum
354d0 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ent is NULL then
354e0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
354f0 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65  unction is.** de
35500 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c  leted.  ^When al
35510 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  l collating func
35520 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65  tions having the
35530 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64   same name are d
35540 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20  eleted,.** that 
35550 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20  collation is no 
35560 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a  longer usable..*
35570 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74  *.** ^The collat
35580 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
35590 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
355a0 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20   with a copy of 
355b0 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70  the pArg .** app
355c0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
355d0 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20 74  inter and with t
355e0 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68  wo strings in th
355f0 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69  e encoding speci
35600 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65  fied.** by the e
35610 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74  TextRep argument
35620 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  .  The collating
35630 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72   function must r
35640 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65  eturn an.** inte
35650 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67 61  ger that is nega
35660 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70  tive, zero, or p
35670 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68  ositive.** if th
35680 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69  e first string i
35690 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75  s less than, equ
356a0 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65  al to, or greate
356b0 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e  r than the secon
356c0 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  d,.** respective
356d0 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67  ly.  A collating
356e0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61   function must a
356f0 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65  lways return the
35700 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20   same answer.** 
35710 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69  given the same i
35720 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f  nputs.  If two o
35730 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67  r more collating
35740 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72   functions are r
35750 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20  egistered.** to 
35760 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69  the same collati
35770 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64  on name (using d
35780 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65  ifferent eTextRe
35790 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61  p values) then a
357a0 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20  ll.** must give 
357b0 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  an equivalent an
357c0 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65  swer when invoke
357d0 64 20 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e  d with equivalen
357e0 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  t strings..** Th
357f0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
35800 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74  tion must obey t
35810 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f  he following pro
35820 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a  perties for all.
35830 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c  ** strings A, B,
35840 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f   and C:.**.** <o
35850 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d  l>.** <li> If A=
35860 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a  =B then B==A..**
35870 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e   <li> If A==B an
35880 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43  d B==C then A==C
35890 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c  ..** <li> If A&l
358a0 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e  t;B THEN B&gt;A.
358b0 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74  .** <li> If A&lt
358c0 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68  ;B and B&lt;C th
358d0 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f  en A&lt;C..** </
358e0 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63  ol>.**.** If a c
358f0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
35900 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74  n fails any of t
35910 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61  he above constra
35920 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a  ints and that.**
35930 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
35940 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65 72  ion is  register
35950 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65  ed and used, the
35960 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
35970 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75  f SQLite.** is u
35980 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
35990 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65  ^The sqlite3_cre
359a0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
359b0 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  () works like sq
359c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
359d0 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68  lation().** with
359e0 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68   the addition th
359f0 61 74 20 74 68 65 20 78 44 65 73 74 72 6f 79 20  at the xDestroy 
35a00 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
35a10 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e  ked on pArg when
35a20 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  .** the collatin
35a30 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  g function is de
35a40 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  leted..** ^Colla
35a50 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61  ting functions a
35a60 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  re deleted when 
35a70 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64  they are overrid
35a80 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20  den by later.** 
35a90 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c  calls to the col
35aa0 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  lation creation 
35ab0 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65  functions or whe
35ac0 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  n the.** [databa
35ad0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
35ae0 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b  s closed using [
35af0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
35b00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65  ..**.** ^The xDe
35b10 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69  stroy callback i
35b20 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c  s <u>not</u> cal
35b30 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73  led if the .** s
35b40 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
35b50 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e  llation_v2() fun
35b60 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70  ction fails.  Ap
35b70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
35b80 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
35b90 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
35ba0 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e  on_v2() with a n
35bb0 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79  on-NULL xDestroy
35bc0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
35bd0 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72   .** check the r
35be0 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64  eturn code and d
35bf0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70  ispose of the ap
35c00 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
35c10 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65  ointer.** themse
35c20 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 61 6e  lves rather than
35c30 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74   expecting SQLit
35c40 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69  e to deal with i
35c50 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54  t for them..** T
35c60 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e 74  his is different
35c70 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65   from every othe
35c80 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
35c90 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69  ce.  The inconsi
35ca0 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e  stency .** is un
35cb0 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63 61  fortunate but ca
35cc0 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20  nnot be changed 
35cd0 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
35ce0 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63   backwards .** c
35cf0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
35d00 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
35d10 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
35d20 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20  n_needed()] and 
35d30 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
35d40 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
35d50 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
35d60 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
35d70 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
35d80 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
35d90 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
35da0 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
35db0 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
35dc0 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
35dd0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
35de0 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  nst void*).);.in
35df0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
35e00 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20  _collation_v2(. 
35e10 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
35e20 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
35e30 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
35e40 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
35e50 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
35e60 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
35e70 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
35e80 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  t void*),.  void
35e90 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
35ea0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
35eb0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
35ec0 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  on16(.  sqlite3*
35ed0 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  , .  const void 
35ee0 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54  *zName,.  int eT
35ef0 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
35f00 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
35f10 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
35f20 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
35f30 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
35f40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35f50 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65  F: Collation Nee
35f60 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ded Callbacks.**
35f70 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61  .** ^To avoid ha
35f80 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72  ving to register
35f90 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   all collation s
35fa0 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20  equences before 
35fb0 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61  a database.** ca
35fc0 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e  n be used, a sin
35fd0 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  gle callback fun
35fe0 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
35ff0 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65  istered with the
36000 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
36010 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20  nnection] to be 
36020 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
36030 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   an undefined co
36040 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
36050 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e  nce is required.
36060 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
36070 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73  unction is regis
36080 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
36090 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
360a0 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a  n_needed() API,.
360b0 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61  ** then it is pa
360c0 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f  ssed the names o
360d0 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  f undefined coll
360e0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
360f0 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e  as strings.** en
36100 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20  coded in UTF-8. 
36110 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ^If sqlite3_coll
36120 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
36130 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65   is used,.** the
36140 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65   names are passe
36150 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d  d as UTF-16 in m
36160 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79  achine native by
36170 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20  te order..** ^A 
36180 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66  call to either f
36190 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73  unction replaces
361a0 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f   the existing co
361b0 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63  llation-needed c
361c0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
361d0 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  (When the callba
361e0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  ck is invoked, t
361f0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
36200 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f  t passed is a co
36210 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63  py.** of the sec
36220 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
36230 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
36240 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a  n_needed() or.**
36250 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
36260 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20  on_needed16().  
36270 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
36280 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62  ent is the datab
36290 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
362a0 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  n.  The third ar
362b0 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
362c0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
362d0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
362e0 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
362f0 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61  UTF16LE], indica
36300 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65  ting the most de
36310 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20  sirable form of 
36320 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  the collation.**
36330 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69   sequence functi
36340 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68  on required.  Th
36350 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
36360 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
36370 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65  f the.** require
36380 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
36390 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  ence.)^.**.** Th
363a0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
363b0 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73  ion should regis
363c0 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20  ter the desired 
363d0 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a  collation using.
363e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
363f0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c  te_collation()],
36400 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
36410 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c  _collation16()],
36420 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
36430 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36440 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  _v2()]..*/.int s
36450 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
36460 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74  _needed(.  sqlit
36470 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a  e3*, .  void*, .
36480 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
36490 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
364a0 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72  xtRep,const char
364b0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
364c0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
364d0 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  ed16(.  sqlite3*
364e0 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f  , .  void*,.  vo
364f0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
36500 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
36510 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  p,const void*).)
36520 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  ;..#ifdef SQLITE
36530 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a  _HAS_CODEC./*.**
36540 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79   Specify the key
36550 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65   for an encrypte
36560 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69  d database.  Thi
36570 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  s routine should
36580 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69   be.** called ri
36590 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65  ght after sqlite
365a0 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_open()..**.** 
365b0 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
365c0 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
365d0 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
365e0 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
365f0 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
36600 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
36610 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  e3_key(.  sqlite
36620 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
36630 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
36640 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
36650 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
36660 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
36670 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65  ey     /* The ke
36680 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  y */.);.int sqli
36690 74 65 33 5f 6b 65 79 5f 76 32 28 0a 20 20 73 71  te3_key_v2(.  sq
366a0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
366b0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
366c0 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
366d0 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
366e0 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c  t char *zDbName,
366f0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61             /* Na
36700 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
36710 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  se */.  const vo
36720 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
36730 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65  ey     /* The ke
36740 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
36750 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e  hange the key on
36760 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
36770 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65  e.  If the curre
36780 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e  nt database is n
36790 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c  ot.** encrypted,
367a0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
367b0 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20  ll encrypt it.  
367c0 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e  If pNew==0 or nN
367d0 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61  ew==0, the.** da
367e0 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70  tabase is decryp
367f0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ted..**.** The c
36800 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
36810 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
36820 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
36830 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
36840 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
36850 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
36860 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
36870 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
36880 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
36890 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
368a0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
368b0 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
368c0 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b      /* The new k
368d0 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ey */.);.int sql
368e0 69 74 65 33 5f 72 65 6b 65 79 5f 76 32 28 0a 20  ite3_rekey_v2(. 
368f0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
36900 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36910 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
36920 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
36930 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
36940 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  me,           /*
36950 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   Name of the dat
36960 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
36970 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
36980 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
36990 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   new key */.);..
369a0 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
369b0 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79  e activation key
369c0 20 66 6f 72 20 61 20 53 45 45 20 64 61 74 61 62   for a SEE datab
369d0 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a  ase.  Unless .**
369e0 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65   activated, none
369f0 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75 74   of the SEE rout
36a00 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a  ines will work..
36a10 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
36a20 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20  activate_see(.  
36a30 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73  const char *zPas
36a40 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f  sPhrase        /
36a50 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72  * Activation phr
36a60 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66  ase */.);.#endif
36a70 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  ..#ifdef SQLITE_
36a80 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a  ENABLE_CEROD./*.
36a90 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61  ** Specify the a
36aa0 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f  ctivation key fo
36ab0 72 20 61 20 43 45 52 4f 44 20 64 61 74 61 62 61  r a CEROD databa
36ac0 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20  se.  Unless .** 
36ad0 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20  activated, none 
36ae0 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75  of the CEROD rou
36af0 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e  tines will work.
36b00 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
36b10 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28  _activate_cerod(
36b20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
36b30 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20  PassPhrase      
36b40 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20    /* Activation 
36b50 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e  phrase */.);.#en
36b60 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
36b70 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65  REF: Suspend Exe
36b80 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f  cution For A Sho
36b90 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68  rt Time.**.** Th
36ba0 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  e sqlite3_sleep(
36bb0 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  ) function cause
36bc0 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68  s the current th
36bd0 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20  read to suspend 
36be0 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72  execution.** for
36bf0 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62   at least a numb
36c00 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
36c10 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  ds specified in 
36c20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  its parameter..*
36c30 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72  *.** If the oper
36c40 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65  ating system doe
36c50 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c  s not support sl
36c60 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74  eep requests wit
36c70 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  h.** millisecond
36c80 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e   time resolution
36c90 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20  , then the time 
36ca0 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20  will be rounded 
36cb0 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61  up to.** the nea
36cc0 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65  rest second. The
36cd0 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
36ce0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
36cf0 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71   actually.** req
36d00 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20  uested from the 
36d10 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
36d20 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
36d30 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c  .** ^SQLite impl
36d40 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65  ements this inte
36d50 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67  rface by calling
36d60 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a   the xSleep().**
36d70 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64   method of the d
36d80 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
36d90 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66  vfs] object.  If
36da0 20 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65   the xSleep() me
36db0 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64  thod.** of the d
36dc0 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 6e 6f  efault VFS is no
36dd0 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f  t implemented co
36de0 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20  rrectly, or not 
36df0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a  implemented at.*
36e00 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20  * all, then the 
36e10 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
36e20 74 65 33 5f 73 6c 65 65 70 28 29 20 6d 61 79 20  te3_sleep() may 
36e30 64 65 76 69 61 74 65 20 66 72 6f 6d 20 74 68 65  deviate from the
36e40 20 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20   description.** 
36e50 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
36e60 70 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 69  paragraphs..*/.i
36e70 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  nt sqlite3_sleep
36e80 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
36e90 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
36ea0 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69  The Folder Holdi
36eb0 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c  ng Temporary Fil
36ec0 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68  es.**.** ^(If th
36ed0 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  is global variab
36ee0 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  le is made to po
36ef0 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
36f00 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20  which is.** the 
36f10 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72  name of a folder
36f20 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f   (a.k.a. directo
36f30 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65  ry), then all te
36f40 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a  mporary files.**
36f50 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69   created by SQLi
36f60 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20  te when using a 
36f70 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65  built-in [sqlite
36f80 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20  3_vfs | VFS].** 
36f90 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69  will be placed i
36fa0 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79  n that directory
36fb0 2e 29 5e 20 20 5e 49 66 20 74 68 69 73 20 76 61  .)^  ^If this va
36fc0 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e  riable.** is a N
36fd0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
36fe0 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d  n SQLite perform
36ff0 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61  s a search for a
37000 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a  n appropriate.**
37010 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20   temporary file 
37020 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
37030 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
37040 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
37050 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  y this variable 
37060 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  in more than one
37070 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 20  .** thread at a 
37080 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74  time.  It is not
37090 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72   safe to read or
370a0 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
370b0 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64  iable.** if a [d
370c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
370d0 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65  on] is being use
370e0 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  d at the same ti
370f0 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 65  me in a separate
37100 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49  .** thread..** I
37110 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68  t is intended th
37120 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
37130 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20   be set once.** 
37140 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65  as part of proce
37150 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
37160 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79  n and before any
37170 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
37180 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61  e.** routines ha
37190 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61  ve been called a
371a0 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  nd that this var
371b0 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63  iable remain unc
371c0 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61  hanged.** therea
371d0 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  fter..**.** ^The
371e0 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
371f0 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d  ectory pragma] m
37200 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  ay modify this v
37210 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73  ariable and caus
37220 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74  e.** it to point
37230 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   to memory obtai
37240 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
37250 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72  3_malloc].  ^Fur
37260 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65  thermore,.** the
37270 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
37280 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61  ectory pragma] a
37290 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68  lways assumes th
372a0 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a  at any string.**
372b0 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
372c0 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73  ble points to is
372d0 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20   held in memory 
372e0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a  obtained from .*
372f0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
37300 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d  c] and the pragm
37310 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f  a may attempt to
37320 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72   free that memor
37330 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  y.** using [sqli
37340 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65  te3_free]..** He
37350 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72  nce, if this var
37360 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65  iable is modifie
37370 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68  d directly, eith
37380 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a  er it should be.
37390 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20  ** made NULL or 
373a0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
373b0 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
373c0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
373d0 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73  alloc].** or els
373e0 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  e the use of the
373f0 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
37400 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73  ectory pragma] s
37410 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64  hould be avoided
37420 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
37430 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69  to Windows Runti
37440 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  me users:</b>  T
37450 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72  he temporary dir
37460 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73  ectory must be s
37470 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63  et.** prior to c
37480 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
37490 6f 70 65 6e 5d 20 6f 72 20 5b 73 71 6c 69 74 65  open] or [sqlite
374a0 33 5f 6f 70 65 6e 5f 76 32 5d 2e 20 20 4f 74 68  3_open_v2].  Oth
374b0 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a  erwise, various.
374c0 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74  ** features that
374d0 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65   require the use
374e0 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69   of temporary fi
374f0 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 20 20 48  les may fail.  H
37500 65 72 65 20 69 73 20 61 6e 0a 2a 2a 20 65 78 61  ere is an.** exa
37510 6d 70 6c 65 20 6f 66 20 68 6f 77 20 74 6f 20 64  mple of how to d
37520 6f 20 74 68 69 73 20 75 73 69 6e 67 20 43 2b 2b  o this using C++
37530 20 77 69 74 68 20 74 68 65 20 57 69 6e 64 6f 77   with the Window
37540 73 20 52 75 6e 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a  s Runtime:.**.**
37550 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
37560 65 3e 0a 2a 2a 20 4c 50 43 57 53 54 52 20 7a 50  e>.** LPCWSTR zP
37570 61 74 68 20 3d 20 57 69 6e 64 6f 77 73 3a 3a 53  ath = Windows::S
37580 74 6f 72 61 67 65 3a 3a 41 70 70 6c 69 63 61 74  torage::Applicat
37590 69 6f 6e 44 61 74 61 3a 3a 43 75 72 72 65 6e 74  ionData::Current
375a0 2d 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20  ->.** &nbsp;    
375b0 20 54 65 6d 70 6f 72 61 72 79 46 6f 6c 64 65 72   TemporaryFolder
375c0 2d 3e 50 61 74 68 2d 3e 44 61 74 61 28 29 3b 0a  ->Path->Data();.
375d0 2a 2a 20 63 68 61 72 20 7a 50 61 74 68 42 75 66  ** char zPathBuf
375e0 26 23 39 31 3b 4d 41 58 5f 50 41 54 48 20 2b 20  &#91;MAX_PATH + 
375f0 31 26 23 39 33 3b 3b 0a 2a 2a 20 6d 65 6d 73 65  1&#93;;.** memse
37600 74 28 7a 50 61 74 68 42 75 66 2c 20 30 2c 20 73  t(zPathBuf, 0, s
37610 69 7a 65 6f 66 28 7a 50 61 74 68 42 75 66 29 29  izeof(zPathBuf))
37620 3b 0a 2a 2a 20 57 69 64 65 43 68 61 72 54 6f 4d  ;.** WideCharToM
37630 75 6c 74 69 42 79 74 65 28 43 50 5f 55 54 46 38  ultiByte(CP_UTF8
37640 2c 20 30 2c 20 7a 50 61 74 68 2c 20 2d 31 2c 20  , 0, zPath, -1, 
37650 7a 50 61 74 68 42 75 66 2c 20 73 69 7a 65 6f 66  zPathBuf, sizeof
37660 28 7a 50 61 74 68 42 75 66 29 2c 0a 2a 2a 20 26  (zPathBuf),.** &
37670 6e 62 73 70 3b 20 20 20 20 20 4e 55 4c 4c 2c 20  nbsp;     NULL, 
37680 4e 55 4c 4c 29 3b 0a 2a 2a 20 73 71 6c 69 74 65  NULL);.** sqlite
37690 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
376a0 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
376b0 74 66 28 22 25 73 22 2c 20 7a 50 61 74 68 42 75  tf("%s", zPathBu
376c0 66 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  f);.** </pre></b
376d0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2f 0a 53 51  lockquote>.*/.SQ
376e0 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72  LITE_EXTERN char
376f0 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64   *sqlite3_temp_d
37700 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a  irectory;../*.**
37710 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
37720 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f  Of The Folder Ho
37730 6c 64 69 6e 67 20 44 61 74 61 62 61 73 65 20 46  lding Database F
37740 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  iles.**.** ^(If 
37750 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69  this global vari
37760 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20  able is made to 
37770 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
37780 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68  g which is.** th
37790 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64  e name of a fold
377a0 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63  er (a.k.a. direc
377b0 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20  tory), then all 
377c0 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 0a 2a  database files.*
377d0 2a 20 73 70 65 63 69 66 69 65 64 20 77 69 74 68  * specified with
377e0 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68   a relative path
377f0 6e 61 6d 65 20 61 6e 64 20 63 72 65 61 74 65 64  name and created
37800 20 6f 72 20 61 63 63 65 73 73 65 64 20 62 79 0a   or accessed by.
37810 2a 2a 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75  ** SQLite when u
37820 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20  sing a built-in 
37830 77 69 6e 64 6f 77 73 20 5b 73 71 6c 69 74 65 33  windows [sqlite3
37840 5f 76 66 73 20 7c 20 56 46 53 5d 20 77 69 6c 6c  _vfs | VFS] will
37850 20 62 65 20 61 73 73 75 6d 65 64 0a 2a 2a 20 74   be assumed.** t
37860 6f 20 62 65 20 72 65 6c 61 74 69 76 65 20 74 6f  o be relative to
37870 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e   that directory.
37880 29 5e 20 5e 49 66 20 74 68 69 73 20 76 61 72 69  )^ ^If this vari
37890 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 0a 2a  able is a NULL.*
378a0 2a 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  * pointer, then 
378b0 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
378c0 68 61 74 20 61 6c 6c 20 64 61 74 61 62 61 73 65  hat all database
378d0 20 66 69 6c 65 73 20 73 70 65 63 69 66 69 65 64   files specified
378e0 0a 2a 2a 20 77 69 74 68 20 61 20 72 65 6c 61 74  .** with a relat
378f0 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61 72 65  ive pathname are
37900 20 72 65 6c 61 74 69 76 65 20 74 6f 20 74 68 65   relative to the
37910 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
37920 72 79 0a 2a 2a 20 66 6f 72 20 74 68 65 20 70 72  ry.** for the pr
37930 6f 63 65 73 73 2e 20 20 4f 6e 6c 79 20 74 68 65  ocess.  Only the
37940 20 77 69 6e 64 6f 77 73 20 56 46 53 20 6d 61 6b   windows VFS mak
37950 65 73 20 75 73 65 20 6f 66 20 74 68 69 73 20 67  es use of this g
37960 6c 6f 62 61 6c 0a 2a 2a 20 76 61 72 69 61 62 6c  lobal.** variabl
37970 65 3b 20 69 74 20 69 73 20 69 67 6e 6f 72 65 64  e; it is ignored
37980 20 62 79 20 74 68 65 20 75 6e 69 78 20 56 46 53   by the unix VFS
37990 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 6e 67 69 6e 67  ..**.** Changing
379a0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
379b0 69 73 20 76 61 72 69 61 62 6c 65 20 77 68 69 6c  is variable whil
379c0 65 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  e a database con
379d0 6e 65 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 6f 70  nection is.** op
379e0 65 6e 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e  en can result in
379f0 20 61 20 63 6f 72 72 75 70 74 20 64 61 74 61 62   a corrupt datab
37a00 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ase..**.** It is
37a10 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
37a20 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
37a30 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72   variable in mor
37a40 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68  e than one.** th
37a50 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20  read at a time. 
37a60 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
37a70 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
37a80 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  y this variable.
37a90 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73  ** if a [databas
37aa0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
37ab0 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74   being used at t
37ac0 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20  he same time in 
37ad0 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68  a separate.** th
37ae0 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69  read..** It is i
37af0 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69  ntended that thi
37b00 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65  s variable be se
37b10 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72  t once.** as par
37b20 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69  t of process ini
37b30 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20  tialization and 
37b40 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74  before any SQLit
37b50 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  e interface.** r
37b60 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65  outines have bee
37b70 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61  n called and tha
37b80 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
37b90 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64  remain unchanged
37ba0 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a  .** thereafter..
37bb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 64 61 74 61  **.** ^The [data
37bc0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
37bd0 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64   pragma] may mod
37be0 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
37bf0 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69  e and cause.** i
37c00 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  t to point to me
37c10 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
37c20 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
37c30 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f  oc].  ^Furthermo
37c40 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 64 61 74 61  re,.** the [data
37c50 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
37c60 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20   pragma] always 
37c70 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79  assumes that any
37c80 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20   string.** that 
37c90 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f  this variable po
37ca0 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20  ints to is held 
37cb0 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  in memory obtain
37cc0 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
37cd0 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64  ite3_malloc] and
37ce0 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20   the pragma may 
37cf0 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20  attempt to free 
37d00 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75  that memory.** u
37d10 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
37d20 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69  ee]..** Hence, i
37d30 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
37d40 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65  is modified dire
37d50 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20  ctly, either it 
37d60 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64  should be.** mad
37d70 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74  e NULL or made t
37d80 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
37d90 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
37da0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
37db0 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20  .** or else the 
37dc0 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
37dd0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
37de0 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20   pragma] should 
37df0 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53  be avoided..*/.S
37e00 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61  QLITE_EXTERN cha
37e10 72 20 2a 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  r *sqlite3_data_
37e20 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a  directory;../*.*
37e30 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74  * CAPI3REF: Test
37e40 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74   For Auto-Commit
37e50 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44   Mode.** KEYWORD
37e60 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d  S: {autocommit m
37e70 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ode}.**.** ^The 
37e80 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
37e90 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61  commit() interfa
37ea0 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ce returns non-z
37eb0 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69  ero or.** zero i
37ec0 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61  f the given data
37ed0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
37ee0 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20  is or is not in 
37ef0 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c  autocommit mode,
37f00 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
37f10 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  .  ^Autocommit m
37f20 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66  ode is on by def
37f30 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f  ault..** ^Autoco
37f40 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73  mmit mode is dis
37f50 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49  abled by a [BEGI
37f60 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  N] statement..**
37f70 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
37f80 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20  e is re-enabled 
37f90 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72  by a [COMMIT] or
37fa0 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a   [ROLLBACK]..**.
37fb0 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69  ** If certain ki
37fc0 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63  nds of errors oc
37fd0 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65  cur on a stateme
37fe0 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74  nt within a mult
37ff0 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  i-statement.** t
38000 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f  ransaction (erro
38010 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51  rs including [SQ
38020 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c  LITE_FULL], [SQL
38030 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b  ITE_IOERR],.** [
38040 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b  SQLITE_NOMEM], [
38050 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e  SQLITE_BUSY], an
38060 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  d [SQLITE_INTERR
38070 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a  UPT]) then the.*
38080 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69  * transaction mi
38090 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ght be rolled ba
380a0 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
380b0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20  .  The only way 
380c0 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77  to.** find out w
380d0 68 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75  hether SQLite au
380e0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
380f0 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ed back the tran
38100 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a  saction after.**
38110 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20   an error is to 
38120 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f  use this functio
38130 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  n..**.** If anot
38140 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67  her thread chang
38150 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69  es the autocommi
38160 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20  t status of the 
38170 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
38180 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69  ection while thi
38190 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e  s routine is run
381a0 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ning, then the r
381b0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69  eturn value.** i
381c0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  s undefined..*/.
381d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
381e0 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74  autocommit(sqlit
381f0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
38200 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20  I3REF: Find The 
38210 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20  Database Handle 
38220 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  Of A Prepared St
38230 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54  atement.**.** ^T
38240 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  he sqlite3_db_ha
38250 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72  ndle interface r
38260 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61  eturns the [data
38270 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
38280 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68   handle.** to wh
38290 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20  ich a [prepared 
382a0 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e  statement] belon
382b0 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62  gs.  ^The [datab
382c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
382d0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
382e0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
382f0 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61   is the same [da
38300 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
38310 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74  n].** that was t
38320 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
38330 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  t.** to the [sql
38340 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
38350 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20  )] call (or its 
38360 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77  variants) that w
38370 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72  as used to.** cr
38380 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  eate the stateme
38390 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  nt in the first 
383a0 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65  place..*/.sqlite
383b0 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  3 *sqlite3_db_ha
383c0 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndle(sqlite3_stm
383d0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
383e0 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65  3REF: Return The
383f0 20 46 69 6c 65 6e 61 6d 65 20 46 6f 72 20 41 20   Filename For A 
38400 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
38410 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
38420 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61  qlite3_db_filena
38430 6d 65 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63  me(D,N) interfac
38440 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
38450 74 65 72 20 74 6f 20 61 20 66 69 6c 65 6e 61 6d  ter to a filenam
38460 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  e.** associated 
38470 77 69 74 68 20 64 61 74 61 62 61 73 65 20 4e 20  with database N 
38480 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  of connection D.
38490 20 20 5e 54 68 65 20 6d 61 69 6e 20 64 61 74 61    ^The main data
384a0 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 68 61 73  base file.** has
384b0 20 74 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22   the name "main"
384c0 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
384d0 6f 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  o attached datab
384e0 61 73 65 20 4e 20 6f 6e 20 74 68 65 20 64 61 74  ase N on the dat
384f0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
38500 69 6f 6e 20 44 2c 20 6f 72 20 69 66 20 64 61 74  ion D, or if dat
38510 61 62 61 73 65 20 4e 20 69 73 20 61 20 74 65 6d  abase N is a tem
38520 70 6f 72 61 72 79 20 6f 72 20 69 6e 2d 6d 65 6d  porary or in-mem
38530 6f 72 79 20 64 61 74 61 62 61 73 65 2c 20 74 68  ory database, th
38540 65 6e 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  en.** a NULL poi
38550 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
38560 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 6c  ..**.** ^The fil
38570 65 6e 61 6d 65 20 72 65 74 75 72 6e 65 64 20 62  ename returned b
38580 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  y this function 
38590 69 73 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66  is the output of
385a0 20 74 68 65 0a 2a 2a 20 78 46 75 6c 6c 50 61 74   the.** xFullPat
385b0 68 6e 61 6d 65 20 6d 65 74 68 6f 64 20 6f 66 20  hname method of 
385c0 74 68 65 20 5b 56 46 53 5d 2e 20 20 5e 49 6e 20  the [VFS].  ^In 
385d0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
385e0 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 69 6c   filename.** wil
385f0 6c 20 62 65 20 61 6e 20 61 62 73 6f 6c 75 74 65  l be an absolute
38600 20 70 61 74 68 6e 61 6d 65 2c 20 65 76 65 6e 20   pathname, even 
38610 69 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  if the filename 
38620 75 73 65 64 0a 2a 2a 20 74 6f 20 6f 70 65 6e 20  used.** to open 
38630 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 69  the database ori
38640 67 69 6e 61 6c 6c 79 20 77 61 73 20 61 20 55 52  ginally was a UR
38650 49 20 6f 72 20 72 65 6c 61 74 69 76 65 20 70 61  I or relative pa
38660 74 68 6e 61 6d 65 2e 0a 2a 2f 0a 63 6f 6e 73 74  thname..*/.const
38670 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64   char *sqlite3_d
38680 62 5f 66 69 6c 65 6e 61 6d 65 28 73 71 6c 69 74  b_filename(sqlit
38690 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68  e3 *db, const ch
386a0 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f  ar *zDbName);../
386b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
386c0 65 74 65 72 6d 69 6e 65 20 69 66 20 61 20 64 61  etermine if a da
386d0 74 61 62 61 73 65 20 69 73 20 72 65 61 64 2d 6f  tabase is read-o
386e0 6e 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nly.**.** ^The s
386f0 71 6c 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e  qlite3_db_readon
38700 6c 79 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63  ly(D,N) interfac
38710 65 20 72 65 74 75 72 6e 73 20 31 20 69 66 20 74  e returns 1 if t
38720 68 65 20 64 61 74 61 62 61 73 65 20 4e 0a 2a 2a  he database N.**
38730 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44   of connection D
38740 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79 2c 20 30   is read-only, 0
38750 20 69 66 20 69 74 20 69 73 20 72 65 61 64 2f 77   if it is read/w
38760 72 69 74 65 2c 20 6f 72 20 2d 31 20 69 66 20 4e  rite, or -1 if N
38770 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 6e   is not.** the n
38780 61 6d 65 20 6f 66 20 61 20 64 61 74 61 62 61 73  ame of a databas
38790 65 20 6f 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e on connection 
387a0 44 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  D..*/.int sqlite
387b0 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28 73 71  3_db_readonly(sq
387c0 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74  lite3 *db, const
387d0 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b   char *zDbName);
387e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
387f0 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20  : Find the next 
38800 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
38810 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  nt.**.** ^This i
38820 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nte