/ Hex Artifact Content
Login

Artifact e13a7b64efa8d6a591577e6a5281fb22783c0133:


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 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
2ad0: 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71  K] if.** the [sq
2ae0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73  lite3] object is
2af0: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65   successfully de
2b00: 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20  stroyed and all 
2b10: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65  associated.** re
2b20: 73 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c  sources are deal
2b30: 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  located..**.** ^
2b40: 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
2b50: 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73  connection is as
2b60: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 75 6e  sociated with un
2b70: 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72  finalized prepar
2b80: 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  ed.** statements
2b90: 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73   or unfinished s
2ba0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62  qlite3_backup ob
2bb0: 6a 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74  jects then sqlit
2bc0: 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69  e3_close().** wi
2bd0: 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61 74  ll leave the dat
2be0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2bf0: 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e   open and return
2c00: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
2c10: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
2c20: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
2c30: 6c 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c  led with unfinal
2c40: 69 7a 65 64 20 70 72 65 70 61 72 65 64 20 73 74  ized prepared st
2c50: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f  atements.** and/
2c60: 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71  or unfinished sq
2c70: 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74  lite3_backups, t
2c80: 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
2c90: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f   connection beco
2ca0: 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62  mes.** an unusab
2cb0: 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63  le "zombie" whic
2cc0: 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  h will automatic
2cd0: 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61  ally be dealloca
2ce0: 74 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  ted when the.** 
2cf0: 6c 61 73 74 20 70 72 65 70 61 72 65 64 20 73 74  last prepared st
2d00: 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c  atement is final
2d10: 69 7a 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74  ized or the last
2d20: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20   sqlite3_backup 
2d30: 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20  is.** finished. 
2d40: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f   The sqlite3_clo
2d50: 73 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  se_v2() interfac
2d60: 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  e is intended fo
2d70: 72 20 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f  r use with.** ho
2d80: 73 74 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61  st languages tha
2d90: 74 20 61 72 65 20 67 61 72 62 61 67 65 20 63 6f  t are garbage co
2da0: 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65  llected, and whe
2db0: 72 65 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20  re the order in 
2dc0: 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63  which.** destruc
2dd0: 74 6f 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20  tors are called 
2de0: 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a  is arbitrary..**
2df0: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
2e00: 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33   should [sqlite3
2e10: 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2e20: 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61  lize] all [prepa
2e30: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
2e40: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
2e50: 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d  b_close | close]
2e60: 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c   all [BLOB handl
2e70: 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  es], and .** [sq
2e80: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e  lite3_backup_fin
2e90: 69 73 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c  ish | finish] al
2ea0: 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  l [sqlite3_backu
2eb0: 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63  p] objects assoc
2ec0: 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  iated.** with th
2ed0: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
2ee0: 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65  ct prior to atte
2ef0: 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20  mpting to close 
2f00: 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66  the object.  ^If
2f10: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  .** sqlite3_clos
2f20: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  e_v2() is called
2f30: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20   on a [database 
2f40: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
2f50: 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75   still has.** ou
2f60: 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61  tstanding [prepa
2f70: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
2f80: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
2f90: 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69   and/or.** [sqli
2fa0: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
2fb0: 63 74 73 20 74 68 65 6e 20 69 74 20 72 65 74 75  cts then it retu
2fc0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
2fd0: 61 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61  and the dealloca
2fe0: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75  tion.** of resou
2ff0: 72 63 65 73 20 69 73 20 64 65 66 65 72 72 65 64  rces is deferred
3000: 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70   until all [prep
3010: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
3020: 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  , [BLOB handles]
3030: 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ,.** and [sqlite
3040: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
3050: 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72  s are also destr
3060: 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  oyed..**.** ^If 
3070: 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  an [sqlite3] obj
3080: 65 63 74 20 69 73 20 64 65 73 74 72 6f 79 65 64  ect is destroyed
3090: 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63   while a transac
30a0: 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a  tion is open,.**
30b0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
30c0: 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
30d0: 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
30e0: 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d  *.** The C param
30f0: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
3100: 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b  _close(C)] and [
3110: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
3120: 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  (C)].** must be 
3130: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a  either a NULL.**
3140: 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b   pointer or an [
3150: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
3160: 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64  pointer obtained
3170: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3180: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
3190: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f  te3_open16()], o
31a0: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
31b0: 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f  en_v2()], and no
31c0: 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f  t previously clo
31d0: 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  sed..** ^Calling
31e0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
31f0: 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73   or sqlite3_clos
3200: 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55  e_v2() with a NU
3210: 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72  LL pointer.** ar
3220: 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d  gument is a harm
3230: 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69  less no-op..*/.i
3240: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
3250: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69 6e 74 20  (sqlite3*);.int 
3260: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
3270: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
3280: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20  ** The type for 
3290: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
32a0: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ion..** This is 
32b0: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65  legacy and depre
32c0: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e  cated.  It is in
32d0: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f  cluded for histo
32e0: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69  rical.** compati
32f0: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f  bility and is no
3300: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f  t documented..*/
3310: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73  .typedef int (*s
3320: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29  qlite3_callback)
3330: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
3340: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a  *, char**);../*.
3350: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65  ** CAPI3REF: One
3360: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63  -Step Query Exec
3370: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a  ution Interface.
3380: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
3390: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
33a0: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65  ce is a convenie
33b0: 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75  nce wrapper arou
33c0: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  nd.** [sqlite3_p
33d0: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
33e0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
33f0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  and [sqlite3_fin
3400: 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61  alize()],.** tha
3410: 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c  t allows an appl
3420: 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d  ication to run m
3430: 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e  ultiple statemen
3440: 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74  ts of SQL.** wit
3450: 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75  hout having to u
3460: 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f  se a lot of C co
3470: 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de. .**.** ^The 
3480: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3490: 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65  nterface runs ze
34a0: 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38  ro or more UTF-8
34b0: 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d   encoded,.** sem
34c0: 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20  icolon-separate 
34d0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70  SQL statements p
34e0: 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32  assed into its 2
34f0: 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20  nd argument,.** 
3500: 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f  in the context o
3510: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
3520: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73  connection] pass
3530: 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73 74  ed in as its 1st
3540: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  .** argument.  ^
3550: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
3560: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20  function of the 
3570: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  3rd argument to.
3580: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3590: 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  ) is not NULL, t
35a0: 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  hen it is invoke
35b0: 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c  d for each resul
35c0: 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20  t row.** coming 
35d0: 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75  out of the evalu
35e0: 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
35f0: 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61  nts.  ^The 4th a
3600: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3610: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3620: 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20  relayed through 
3630: 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 6d  to the 1st argum
3640: 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63  ent of each.** c
3650: 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69  allback invocati
3660: 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  on.  ^If the cal
3670: 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f  lback pointer to
3680: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3690: 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ** is NULL, then
36a0: 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20   no callback is 
36b0: 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64  ever invoked and
36c0: 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65   result rows are
36d0: 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  .** ignored..**.
36e0: 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20  ** ^If an error 
36f0: 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 61  occurs while eva
3700: 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20  luating the SQL 
3710: 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65  statements passe
3720: 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  d into.** sqlite
3730: 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65  3_exec(), then e
3740: 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
3750: 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e  current statemen
3760: 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73  t stops and.** s
3770: 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d  ubsequent statem
3780: 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 64  ents are skipped
3790: 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  .  ^If the 5th p
37a0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
37b0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
37c0: 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61   not NULL then a
37d0: 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ny error message
37e0: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
37f0: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
3800: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3810: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
3820: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f  passed back thro
3830: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3840: 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f  meter..** To avo
3850: 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c  id memory leaks,
3860: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
3870: 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b   should invoke [
3880: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a  sqlite3_free()].
3890: 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73  ** on error mess
38a0: 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  age strings retu
38b0: 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65  rned through the
38c0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   5th parameter o
38d0: 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  f.** of sqlite3_
38e0: 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65  exec() after the
38f0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3900: 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67  tring is no long
3910: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49  er needed..** ^I
3920: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3930: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3940: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  xec() is not NUL
3950: 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a  L and no errors.
3960: 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73  ** occur, then s
3970: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65  qlite3_exec() se
3980: 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69  ts the pointer i
3990: 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65  n its 5th parame
39a0: 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62  ter to.** NULL b
39b0: 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
39c0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71  .**.** ^If an sq
39d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
39e0: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
39f0: 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69  n-zero, the sqli
3a00: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f  te3_exec().** ro
3a10: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51  utine returns SQ
3a20: 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f  LITE_ABORT witho
3a30: 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  ut invoking the 
3a40: 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61  callback again a
3a50: 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75  nd.** without ru
3a60: 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71  nning any subseq
3a70: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65  uent SQL stateme
3a80: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
3a90: 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  2nd argument to 
3aa0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3ab0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  () callback func
3ac0: 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e  tion is the.** n
3ad0: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
3ae0: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20   in the result. 
3af0: 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65   ^The 3rd argume
3b00: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3b10: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c  3_exec().** call
3b20: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79  back is an array
3b30: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
3b40: 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64  strings obtained
3b50: 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b   as if from.** [
3b60: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
3b70: 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20  ext()], one for 
3b80: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49  each column.  ^I
3b90: 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20  f an element of 
3ba0: 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  a.** result row 
3bb0: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
3bc0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73   corresponding s
3bd0: 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f  tring pointer fo
3be0: 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  r the.** sqlite3
3bf0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3c00: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3c10: 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72  er.  ^The 4th ar
3c20: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
3c30: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3c40: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
3c50: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3c60: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72   to strings wher
3c70: 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20  e each.** entry 
3c80: 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e  represents the n
3c90: 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e  ame of correspon
3ca0: 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75  ding result colu
3cb0: 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mn as obtained.*
3cc0: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3cd0: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a  column_name()]..
3ce0: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e  **.** ^If the 2n
3cf0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
3d00: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3d10: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
3d20: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
3d30: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
3d40: 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  , or a pointer t
3d50: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c  hat contains onl
3d60: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64  y whitespace and
3d70: 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d  /or .** SQL comm
3d80: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
3d90: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
3da0: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74   evaluated and t
3db0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  he database.** i
3dc0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
3dd0: 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e  *.** Restriction
3de0: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
3df0: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3e00: 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72  ation must insur
3e10: 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70  e that the 1st p
3e20: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3e30: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20  te3_exec().**   
3e40: 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e     is a valid an
3e50: 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  d open [database
3e60: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
3e70: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3e80: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63  ation must not c
3e90: 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 61 62 61  lose the [databa
3ea0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
3eb0: 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
3ec0: 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61      the 1st para
3ed0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
3ee0: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
3ef0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3f00: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e  running..** <li>
3f10: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3f20: 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79   must not modify
3f30: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3f40: 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69  nt text passed i
3f50: 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20  nto.**      the 
3f60: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
3f70: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3f80: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
3f90: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
3fa0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ul>.*/.int
3fb0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20   sqlite3_exec(. 
3fc0: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20   sqlite3*,      
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
3ff0: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
4000: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
4010: 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20  *sql,           
4020: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4030: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
4040: 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20  luated */.  int 
4050: 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  (*callback)(void
4060: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61  *,int,char**,cha
4070: 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61  r**),  /* Callba
4080: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  ck function */. 
4090: 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20   void *,        
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31              /* 1
40c0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  st argument to c
40d0: 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61  allback */.  cha
40e0: 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20  r **errmsg      
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4100: 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
4110: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
4120: 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
4130: 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
4140: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
4150: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20  S: {result code 
4160: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
4170: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66  ** Many SQLite f
4180: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
4190: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  an integer resul
41a0: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20  t code from the 
41b0: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72  set shown.** her
41c0: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  e in order to in
41d0: 64 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f  dicate success o
41e0: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  r failure..**.**
41f0: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73   New error codes
4200: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
4210: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
4220: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
4230: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74  * See also: [ext
4240: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4250: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a  e definitions].*
4260: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4270: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
4280: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
4290: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
42a0: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
42b0: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
42c0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
42d0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
42e0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
42f0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
4300: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
4310: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
4320: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
4330: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
4340: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4350: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
4360: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
4370: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
4380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4390: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
43a0: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
43b0: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
43c0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
43d0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
43e0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
43f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
4400: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
4410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4420: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4430: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4440: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4450: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4460: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4470: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4480: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4490: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
44a0: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
44b0: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
44c0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
44d0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
44e0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
44f0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
4500: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
4510: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4520: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4530: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4540: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4550: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4560: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4570: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4580: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4590: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
45a0: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
45b0: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
45c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
45d0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
45e0: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
45f0: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
4600: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
4610: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
4620: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
4630: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
4640: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
4650: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
4660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
4670: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
4680: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
4690: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
46a0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
46b0: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
46c0: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
46d0: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
46e0: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
46f0: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
4700: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
4710: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
4720: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
4730: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
4740: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4750: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
4760: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4770: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
4780: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
4790: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
47a0: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
47b0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
47c0: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
47d0: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
47e0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
47f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4800: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
4810: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
4820: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
4830: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
4840: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
4850: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
4860: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
4870: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
4880: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
4890: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
48a0: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
48b0: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
48c0: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
48d0: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
48e0: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
48f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4900: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
4910: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
4920: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
4930: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4940: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4950: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4960: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4970: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4980: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4990: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
49a0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
49b0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
49c0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
49d0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
49e0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
49f0: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4a00: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4a10: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4a30: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4a40: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4a50: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4a70: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4a80: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4a90: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4aa0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4ab0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4ac0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4ad0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4ae0: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4af0: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4b00: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4b10: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4b20: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4b30: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4b40: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4b50: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4b60: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4b70: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4b80: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4b90: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4ba0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4bb0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4bc0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4bd0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4be0: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4bf0: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4c00: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4c10: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4c20: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4c30: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4c40: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4c50: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4c60: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4c70: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4c80: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4c90: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4ca0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4cb0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4cc0: 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20  .3.8 and later) 
4cd0: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f  include.** suppo
4ce0: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rt for additiona
4cf0: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74  l result codes t
4d00: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65  hat provide more
4d10: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d   detailed inform
4d20: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65  ation.** about e
4d30: 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78  rrors. These [ex
4d40: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4d50: 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64  des] are enabled
4d60: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4d70: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4d80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4d90: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4da0: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4db0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4dc0: 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20  ] API.  Or, the 
4dd0: 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f  extended code fo
4de0: 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  r.** the most re
4df0: 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62  cent error can b
4e00: 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67  e obtained using
4e10: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4e20: 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d  ended_errcode()]
4e30: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4e40: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
4e50: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4e60: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
4e70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e80: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
4e90: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
4ea0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
4eb0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4ec0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
4ed0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4ee0: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
4ef0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4f00: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
4f10: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4f20: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
4f30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4f40: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
4f50: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4f60: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
4f70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4f80: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
4f90: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4fa0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
4fb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4fc0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
4fd0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4fe0: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
4ff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5000: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5010: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5020: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5030: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5040: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5050: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5060: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5070: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5080: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5090: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
50a0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
50b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
50c0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
50d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
50e0: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
50f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5100: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5110: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5120: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5130: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5140: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5150: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5160: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5170: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5180: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5190: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
51a0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
51b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51c0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
51d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
51e0: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
51f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5200: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5210: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5220: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5230: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5240: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5250: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5260: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5270: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5280: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5290: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52a0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
52b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52c0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
52d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52e0: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
52f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5300: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5310: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5320: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5330: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5340: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5350: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5360: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5370: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5380: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5390: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53a0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
53b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53c0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
53d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53e0: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
53f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5400: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
5410: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5420: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
5430: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5440: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
5450: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5460: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5470: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5480: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
5490: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54a0: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
54b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
54c0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
54d0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
54e0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
54f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5500: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5510: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5520: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5530: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5540: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
5550: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5560: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5570: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5580: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5590: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
55a0: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
55b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55c0: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
55d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
55e0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
55f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5600: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
5610: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5620: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
5630: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5640: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
5650: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5660: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5670: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5680: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
5690: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
56a0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
56b0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
56c0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
56d0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
56e0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
56f0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5700: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5710: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
5720: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5730: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
5740: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5750: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5760: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5770: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5780: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5790: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
57a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
57b0: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
57c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
57d0: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
57e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
57f0: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  BORT | (2<<8)).#
5800: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5810: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20  NSTRAINT_CHECK  
5820: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5830: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38  NSTRAINT | (1<<8
5840: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5850: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d  E_CONSTRAINT_COM
5860: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54  MITHOOK   (SQLIT
5870: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5880: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5890: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
58a0: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53  _FOREIGNKEY   (S
58b0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
58c0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
58d0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
58e0: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20  AINT_FUNCTION   
58f0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5900: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23  AINT | (4<<8)).#
5910: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5920: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c  NSTRAINT_NOTNULL
5930: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5940: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38  NSTRAINT | (5<<8
5950: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5960: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49  E_CONSTRAINT_PRI
5970: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54  MARYKEY   (SQLIT
5980: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5990: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
59a0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
59b0: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53  _TRIGGER      (S
59c0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
59d0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
59e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
59f0: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20  AINT_UNIQUE     
5a00: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5a10: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23  AINT | (8<<8)).#
5a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5a30: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20  NSTRAINT_VTAB   
5a40: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5a50: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38  NSTRAINT | (9<<8
5a60: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a70: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57  E_CONSTRAINT_ROW
5a80: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ID        (SQLIT
5a90: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31  E_CONSTRAINT |(1
5aa0: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
5ab0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5ac0: 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53  OVER_WAL      (S
5ad0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5ae0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5af0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5b00: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53  OVER_ROLLBACK (S
5b10: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5b20: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5b30: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55  QLITE_WARNING_AU
5b40: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53  TOINDEX       (S
5b50: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20  QLITE_WARNING | 
5b60: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5b70: 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52  SQLITE_AUTH_USER
5b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28                 (
5b90: 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31  SQLITE_AUTH | (1
5ba0: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
5bb0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
5bc0: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
5bd0: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
5be0: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
5bf0: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
5c00: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
5c10: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5c20: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
5c30: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
5c40: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
5c50: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5c60: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
5c70: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
5c80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c90: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
5ca0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
5cb0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5cc0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5cd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ce0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
5cf0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
5d00: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5d10: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5d20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d30: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
5d40: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
5d50: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5d60: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5d70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d80: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
5d90: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
5da0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5db0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5dc0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
5dd0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
5de0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5df0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e00: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
5e10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5e20: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5e30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e40: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
5e50: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
5e60: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5e70: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5e80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e90: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20  OPEN_MEMORY     
5ea0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
5eb0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5ec0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5ed0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ee0: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
5ef0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
5f00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5f10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f20: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
5f30: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
5f40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5f50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f60: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
5f70: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
5f80: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5f90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5fa0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
5fb0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
5fc0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5fd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5fe0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
5ff0: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
6000: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6010: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6020: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
6030: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
6040: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6050: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6060: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
6070: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
6080: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6090: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
60a0: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
60b0: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
60c0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
60d0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
60e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
60f0: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
6100: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
6110: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6120: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6130: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6140: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
6150: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
6160: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6170: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6180: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6190: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
61a0: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
61b0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
61c0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
61d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
61e0: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
61f0: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
6200: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6210: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20  ../* Reserved:  
6220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6230: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30         0x00F0000
6240: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0 */../*.** CAPI
6250: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
6260: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a  racteristics.**.
6270: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68  ** The xDeviceCh
6280: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
6290: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
62a0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
62b0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
62c0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
62d0: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
62e0: 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  of these.** bit 
62f0: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
6300: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
6310: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
6320: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
6330: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
6340: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
6350: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6360: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
6370: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
6380: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6390: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
63a0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
63b0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
63c0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
63d0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
63e0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
63f0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
6400: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
6410: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
6420: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
6430: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
6440: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
6450: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
6460: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
6470: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
6480: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
6490: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
64a0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
64b0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
64c0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
64d0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
64e0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
64f0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
6500: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
6510: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
6520: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
6530: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
6540: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
6550: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
6560: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
6570: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
6580: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
6590: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
65a0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
65b0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
65c0: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
65d0: 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20  RWRITE property 
65e0: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66  means that.** af
65f0: 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f  ter reboot follo
6600: 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20  wing a crash or 
6610: 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20  power loss, the 
6620: 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a  only bytes in a.
6630: 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72  ** file that wer
6640: 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65  e written at the
6650: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76   application lev
6660: 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68  el might have ch
6670: 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61  anged.** and tha
6680: 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73  t adjacent bytes
6690: 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74  , even bytes wit
66a0: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63  hin the same sec
66b0: 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61  tor are.** guara
66c0: 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68  nteed to be unch
66d0: 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49  anged.  The SQLI
66e0: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
66f0: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a  ABLE_WHEN_OPEN.*
6700: 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 20  * flag indicate 
6710: 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e  that a file cann
6720: 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 68  ot be deleted wh
6730: 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a  en open.  The.**
6740: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d   SQLITE_IOCAP_IM
6750: 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64  MUTABLE flag ind
6760: 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20  icates that the 
6770: 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65  file is on.** re
6780: 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e  ad-only media an
6790: 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  d cannot be chan
67a0: 67 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63  ged even by proc
67b0: 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c  esses with.** el
67c0: 65 76 61 74 65 64 20 70 72 69 76 69 6c 65 67 65  evated privilege
67d0: 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s..*/.#define SQ
67e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
67f0: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
6800: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65    0x00000001.#de
6810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6820: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20  P_ATOMIC512     
6830: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6840: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
6850: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
6860: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
6870: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
6880: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6890: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
68a0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
68b0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
68c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20  _IOCAP_ATOMIC4K 
68d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
68e0: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65  00000010.#define
68f0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6900: 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20  OMIC8K          
6910: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a       0x00000020.
6920: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6930: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20  OCAP_ATOMIC16K  
6940: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6950: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
6960: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6970: 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20  IC32K           
6980: 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64     0x00000080.#d
6990: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
69a0: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20  AP_ATOMIC64K    
69b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
69c0: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
69d0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
69e0: 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20  PPEND           
69f0: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66   0x00000200.#def
6a00: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6a10: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20  _SEQUENTIAL     
6a20: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34          0x000004
6a30: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6a40: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41  E_IOCAP_UNDELETA
6a50: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30  BLE_WHEN_OPEN  0
6a60: 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e  x00000800.#defin
6a70: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
6a80: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
6a90: 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30  TE    0x00001000
6aa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6ab0: 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20  IOCAP_IMMUTABLE 
6ac0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6ad0: 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0002000../*.** C
6ae0: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
6af0: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
6b00: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
6b10: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
6b20: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
6b30: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
6b40: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
6b50: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
6b60: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
6b70: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
6b80: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
6b90: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
6ba0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6bb0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
6bc0: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
6bd0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
6be0: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
6bf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6c00: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
6c10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6c20: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
6c30: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
6c40: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
6c50: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
6c60: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
6c70: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
6c80: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
6c90: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
6ca0: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
6cb0: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
6cc0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6cd0: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
6ce0: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
6cf0: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
6d00: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
6d10: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
6d20: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
6d30: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
6d40: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
6d50: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
6d60: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
6d70: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
6d80: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
6d90: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
6da0: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
6db0: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
6dc0: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
6dd0: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6de0: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
6df0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
6e00: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
6e10: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
6e20: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
6e30: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
6e40: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
6e50: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
6e60: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
6e70: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
6e80: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
6e90: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
6ea0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
6eb0: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
6ec0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
6ed0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
6ee0: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
6ef0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
6f00: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
6f10: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
6f20: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
6f30: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
6f40: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
6f50: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
6f60: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
6f70: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
6f80: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
6f90: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
6fa0: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
6fb0: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
6fc0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
6fd0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
6fe0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6ff0: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
7000: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
7010: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
7020: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
7030: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
7040: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
7050: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
7060: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
7070: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
7080: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
7090: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
70a0: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
70b0: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
70c0: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
70d0: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
70e0: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
70f0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
7100: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
7110: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
7120: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
7130: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
7140: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
7150: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
7160: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
7170: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7180: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
7190: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
71a0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
71b0: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
71c0: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
71d0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
71e0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
71f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
7200: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
7210: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
7220: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
7230: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
7240: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
7250: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
7260: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
7270: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
7280: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
7290: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
72a0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
72b0: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
72c0: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
72d0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
72e0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
72f0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
7300: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
7310: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
7320: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
7330: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
7340: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
7350: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
7360: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
7370: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
7380: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
7390: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
73a0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
73b0: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
73c0: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
73d0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
73e0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
73f0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
7400: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
7410: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
7420: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
7430: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7440: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
7450: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
7460: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
7470: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
7480: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7490: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
74a0: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
74b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
74c0: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
74d0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
74e0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
74f0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7500: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
7510: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
7520: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
7530: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
7540: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
7550: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
7560: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
7570: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
7580: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
7590: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
75a0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
75b0: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
75c0: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
75d0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
75e0: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
75f0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7600: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
7610: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
7620: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
7630: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7640: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
7650: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
7660: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
7670: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7680: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
7690: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
76a0: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
76b0: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
76c0: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
76d0: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
76e0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
76f0: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
7700: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7710: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
7720: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
7730: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
7740: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
7750: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7760: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
7770: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
7780: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
7790: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
77a0: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
77b0: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
77c0: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
77d0: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
77e0: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
77f0: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
7800: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
7810: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
7820: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
7830: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
7840: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
7850: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
7860: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
7870: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
7880: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
7890: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
78a0: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
78b0: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
78c0: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
78d0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
78e0: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
78f0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
7900: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
7910: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
7920: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
7930: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
7940: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
7950: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
7960: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
7970: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
7980: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
7990: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
79a0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
79b0: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
79c0: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
79d0: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
79e0: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
79f0: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
7a00: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
7a10: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
7a20: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
7a30: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
7a40: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
7a50: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
7a60: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
7a70: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
7a80: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
7a90: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
7aa0: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
7ab0: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
7ac0: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
7ad0: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
7ae0: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
7af0: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
7b00: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7b10: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
7b20: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
7b30: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
7b40: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
7b50: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
7b60: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
7b70: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
7b80: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
7b90: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
7ba0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
7bb0: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
7bc0: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
7bd0: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
7be0: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
7bf0: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
7c00: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
7c10: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
7c20: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
7c30: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
7c40: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
7c50: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
7c60: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
7c70: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
7c80: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
7c90: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
7ca0: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
7cb0: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
7cc0: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
7cd0: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
7ce0: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
7cf0: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
7d00: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
7d10: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
7d20: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
7d30: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
7d40: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
7d50: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
7d60: 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A [file control 
7d70: 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f  opcodes | list o
7d80: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20  f opcodes] less 
7d90: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69  than 100 is avai
7da0: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  lable..** Applic
7db0: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69  ations that defi
7dc0: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c  ne a custom xFil
7dd0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
7de0: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64  should use opcod
7df0: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68  es.** greater th
7e00: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20  an 100 to avoid 
7e10: 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20  conflicts.  VFS 
7e20: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7e30: 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
7e40: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
7e50: 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74  D] for file cont
7e60: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74  rol opcodes that
7e70: 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
7e80: 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a  recognize..**.**
7e90: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65   The xSectorSize
7ea0: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
7eb0: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a  s the sector siz
7ec0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69  e of the.** devi
7ed0: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65  ce that underlie
7ee0: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  s the file.  The
7ef0: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20   sector size is 
7f00: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77  the.** minimum w
7f10: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65  rite that can be
7f20: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f   performed witho
7f30: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a  ut disturbing.**
7f40: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20   other bytes in 
7f50: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78  the file.  The x
7f60: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
7f70: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f  stics().** metho
7f80: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20  d returns a bit 
7f90: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e  vector describin
7fa0: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74  g behaviors of t
7fb0: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
7fc0: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c   device:.**.** <
7fd0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
7fe0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7ff0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8000: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
8010: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  2].** <li> [SQLI
8020: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
8030: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8040: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
8050: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8060: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
8070: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8080: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
8090: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
80a0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
80b0: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  6K].** <li> [SQL
80c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
80d0: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  32K].** <li> [SQ
80e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
80f0: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C64K].** <li> [S
8100: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8110: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e  _APPEND].** <li>
8120: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
8130: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f  EQUENTIAL].** </
8140: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  ul>.**.** The SQ
8150: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8160: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
8170: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
8180: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
8190: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
81a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
81b0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
81c0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
81d0: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
81e0: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
81f0: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
8200: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
8210: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
8220: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
8230: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
8240: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
8250: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
8260: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
8270: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
8280: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
8290: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
82a0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
82b0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
82c0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
82d0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
82e0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
82f0: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
8300: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
8310: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
8320: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8330: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
8340: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
8350: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
8360: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
8370: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
8380: 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28  .**.** If xRead(
8390: 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
83a0: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
83b0: 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66  D it must also f
83c0: 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e  ill.** in the un
83d0: 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66  read portions of
83e0: 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68   the buffer with
83f0: 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74   zeros.  A VFS t
8400: 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20  hat.** fails to 
8410: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
8420: 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d  reads might seem
8430: 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76   to work.  Howev
8440: 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74  er,.** failure t
8450: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
8460: 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65  t reads will eve
8470: 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a  ntually lead to.
8480: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72  ** database corr
8490: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  uption..*/.typed
84a0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
84b0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c  3_io_methods sql
84c0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b  ite3_io_methods;
84d0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
84e0: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69  io_methods {.  i
84f0: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
8500: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
8510: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
8520: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69  nt (*xRead)(sqli
8530: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a  te3_file*, void*
8540: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
8550: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
8560: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65  ;.  int (*xWrite
8570: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8580: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
8590: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
85a0: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
85b0: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29  int (*xTruncate)
85c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
85d0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69  sqlite3_int64 si
85e0: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ze);.  int (*xSy
85f0: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  nc)(sqlite3_file
8600: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  *, int flags);. 
8610: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65   int (*xFileSize
8620: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8630: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
8640: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a  pSize);.  int (*
8650: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  xLock)(sqlite3_f
8660: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
8670: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c  t (*xUnlock)(sql
8680: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
8690: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b  ;.  int (*xCheck
86a0: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71  ReservedLock)(sq
86b0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
86c0: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
86d0: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  t (*xFileControl
86e0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
86f0: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70   int op, void *p
8700: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Arg);.  int (*xS
8710: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74  ectorSize)(sqlit
8720: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8730: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63   (*xDeviceCharac
8740: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74  teristics)(sqlit
8750: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20  e3_file*);.  /* 
8760: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8770: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8780: 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 1 */.  int (
8790: 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65  *xShmMap)(sqlite
87a0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67  3_file*, int iPg
87b0: 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c  , int pgsz, int,
87c0: 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a   void volatile**
87d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c  );.  int (*xShmL
87e0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
87f0: 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20  e*, int offset, 
8800: 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73  int n, int flags
8810: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d  );.  void (*xShm
8820: 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33  Barrier)(sqlite3
8830: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8840: 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69  *xShmUnmap)(sqli
8850: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64  te3_file*, int d
8860: 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a  eleteFlag);.  /*
8870: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
8880: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
8890: 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20  sion 2 */.  int 
88a0: 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65  (*xFetch)(sqlite
88b0: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
88c0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e  _int64 iOfst, in
88d0: 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70  t iAmt, void **p
88e0: 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66  p);.  int (*xUnf
88f0: 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69  etch)(sqlite3_fi
8900: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
8910: 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a  64 iOfst, void *
8920: 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  p);.  /* Methods
8930: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
8940: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a   for version 3 *
8950: 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  /.  /* Additiona
8960: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
8970: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
8980: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
8990: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
89a0: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
89b0: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a  ontrol Opcodes.*
89c0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c  * KEYWORDS: {fil
89d0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
89e0: 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  s} {file control
89f0: 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54   opcode}.**.** T
8a00: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
8a10: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
8a20: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
8a30: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
8a40: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
8a50: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
8a60: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
8a70: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
8a80: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
8a90: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
8aa0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8ab0: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
8ac0: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
8ad0: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
8ae0: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
8af0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8b00: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
8b10: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
8b20: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
8b30: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
8b40: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
8b50: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
8b60: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
8b70: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
8b80: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8b90: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
8ba0: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
8bb0: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8bc0: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8bd0: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8be0: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8bf0: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8c00: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8c10: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
8c20: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
8c30: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
8c40: 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  .** is defined..
8c50: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b  ** <ul>.** <li>[
8c60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
8c70: 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65  ZE_HINT]].** The
8c80: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
8c90: 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65  IZE_HINT] opcode
8ca0: 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69   is used by SQLi
8cb0: 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56  te to give the V
8cc0: 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69  FS.** layer a hi
8cd0: 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20  nt of how large 
8ce0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
8cf0: 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62  e will grow to b
8d00: 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20  e during the.** 
8d10: 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
8d20: 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20  ion.  This hint 
8d30: 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  is not guarantee
8d40: 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65  d to be accurate
8d50: 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66   but it.** is of
8d60: 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20  ten close.  The 
8d70: 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d  underlying VFS m
8d80: 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70  ight choose to p
8d90: 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62  reallocate datab
8da0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63  ase.** file spac
8db0: 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20  e based on this 
8dc0: 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  hint in order to
8dd0: 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20   help writes to 
8de0: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
8df0: 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e  file run faster.
8e00: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8e10: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
8e20: 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SIZE]].** The [S
8e30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
8e40: 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69  K_SIZE] opcode i
8e50: 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73  s used to reques
8e60: 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a  t that the VFS.*
8e70: 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72  * extends and tr
8e80: 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61  uncates the data
8e90: 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75  base file in chu
8ea0: 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70  nks of a size sp
8eb0: 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
8ec0: 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72  e user. The four
8ed0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  th argument to [
8ee0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8ef0: 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a  trol()] should .
8f00: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69  ** point to an i
8f10: 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74  nteger (type int
8f20: 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
8f30: 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20   new chunk-size 
8f40: 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68  to use.** for th
8f50: 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61  e nominated data
8f60: 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67  base. Allocating
8f70: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73   database file s
8f80: 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a  pace in large.**
8f90: 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42   chunks (say 1MB
8fa0: 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79   at a time), may
8fb0: 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73   reduce file-sys
8fc0: 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  tem fragmentatio
8fd0: 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65  n and.** improve
8fe0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20   performance on 
8ff0: 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a  some systems..**
9000: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9010: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
9020: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TER]].** The [SQ
9030: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
9040: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
9050: 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  is used to obtai
9060: 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  n a pointer.** t
9070: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  o the [sqlite3_f
9080: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ile] object asso
9090: 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61  ciated with a pa
90a0: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
90b0: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
90c0: 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74    See the [sqlit
90d0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
90e0: 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  )] documentation
90f0: 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
9100: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
9110: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9120: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
9130: 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f  ITTED]].** No lo
9140: 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a  nger in use..**.
9150: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9160: 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20  FCNTL_SYNC]].** 
9170: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9180: 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69  L_SYNC] opcode i
9190: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65  s generated inte
91a0: 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65  rnally by SQLite
91b0: 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20   and.** sent to 
91c0: 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74  the VFS immediat
91d0: 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78  ely before the x
91e0: 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69  Sync method is i
91f0: 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64  nvoked on a.** d
9200: 61 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73  atabase file des
9210: 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20  criptor. Or, if 
9220: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
9230: 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
9240: 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20  .** because the 
9250: 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75  user has configu
9260: 72 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20  red SQLite with 
9270: 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  .** [PRAGMA sync
9280: 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41  hronous | PRAGMA
9290: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46   synchronous=OFF
92a0: 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  ] it is invoked 
92b0: 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20  in place .** of 
92c0: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
92d0: 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c  . In most cases,
92e0: 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   the pointer arg
92f0: 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74  ument passed wit
9300: 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63  h.** this file-c
9310: 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20  ontrol is NULL. 
9320: 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20  However, if the 
9330: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
9340: 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a   being synced.**
9350: 20 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75   as part of a mu
9360: 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d  lti-database com
9370: 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e  mit, the argumen
9380: 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75  t points to a nu
9390: 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
93a0: 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
93b0: 67 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  g the transactio
93c0: 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61  ns master-journa
93d0: 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53  l file name. VFS
93e0: 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e  es that .** do n
93f0: 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  ot need this sig
9400: 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  nal should silen
9410: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
9420: 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74  opcode. Applicat
9430: 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20  ions .** should 
9440: 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65  not call [sqlite
9450: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9460: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
9470: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
9480: 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74  ay .** disrupt t
9490: 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  he operation of 
94a0: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
94b0: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
94c0: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
94d0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
94e0: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
94f0: 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  ETWO]].** The [S
9500: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
9510: 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63  IT_PHASETWO] opc
9520: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
9530: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53   internally by S
9540: 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e  QLite.** and sen
9550: 74 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74  t to the VFS aft
9560: 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
9570: 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74   has been commit
9580: 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a  ted immediately.
9590: 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68  ** but before th
95a0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e  e database is un
95b0: 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68  locked. VFSes th
95c0: 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  at do not need t
95d0: 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68  his signal.** sh
95e0: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
95f0: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
9600: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  . Applications s
9610: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a  hould not call.*
9620: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
9630: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20  control()] with 
9640: 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64  this opcode as d
9650: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72  oing so may disr
9660: 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72  upt the .** oper
9670: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
9680: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74  cialized VFSes t
9690: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69  hat do require i
96a0: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  t.  .**.** <li>[
96b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
96c0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a  N32_AV_RETRY]].*
96d0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
96e0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
96f0: 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TRY] opcode is u
9700: 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
9710: 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65   automatic.** re
9720: 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69  try counts and i
9730: 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72  ntervals for cer
9740: 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70  tain disk I/O op
9750: 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  erations for the
9760: 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53  .** windows [VFS
9770: 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  ] in order to pr
9780: 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73  ovide robustness
9790: 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65   in the presence
97a0: 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75   of.** anti-viru
97b0: 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20  s programs.  By 
97c0: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e  default, the win
97d0: 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65  dows VFS will re
97e0: 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a  try file read,.*
97f0: 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e  * file write, an
9800: 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70  d file delete op
9810: 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31  erations up to 1
9820: 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20  0 times, with a 
9830: 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d  delay.** of 25 m
9840: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f  illiseconds befo
9850: 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74  re the first ret
9860: 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20  ry and with the 
9870: 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67  delay increasing
9880: 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69  .** by an additi
9890: 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63  onal 25 millisec
98a0: 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73  onds with each s
98b0: 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e  ubsequent retry.
98c0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
98d0: 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77   allows these tw
98e0: 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74  o values (10 ret
98f0: 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c  ries and 25 mill
9900: 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61  iseconds of dela
9910: 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75  y).** to be adju
9920: 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65  sted.  The value
9930: 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f  s are changed fo
9940: 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63  r all database c
9950: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69  onnections.** wi
9960: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72  thin the same pr
9970: 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75  ocess.  The argu
9980: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
9990: 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66  r to an array of
99a0: 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73   two.** integers
99b0: 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74   where the first
99c0: 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e   integer i the n
99d0: 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61  ew retry count a
99e0: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  nd the second.**
99f0: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20   integer is the 
9a00: 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65  delay.  If eithe
9a10: 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67  r integer is neg
9a20: 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
9a30: 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f  setting.** is no
9a40: 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e  t changed but in
9a50: 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20  stead the prior 
9a60: 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65  value of that se
9a70: 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e  tting is written
9a80: 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72  .** into the arr
9a90: 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69  ay entry, allowi
9aa0: 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  ng the current r
9ab0: 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f  etry settings to
9ac0: 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61   be.** interroga
9ad0: 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d  ted.  The zDbNam
9ae0: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  e parameter is i
9af0: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  gnored..**.** <l
9b00: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9b10: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a  _PERSIST_WAL]].*
9b20: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9b30: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
9b40: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9b50: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
9b60: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
9b70: 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20  nt [WAL | Write 
9b80: 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69  Ahead Log] setti
9b90: 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ng.  By default,
9ba0: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a   the auxiliary.*
9bb0: 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f  * write ahead lo
9bc0: 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  g and shared mem
9bd0: 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66  ory files used f
9be0: 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63  or transaction c
9bf0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75  ontrol.** are au
9c00: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
9c10: 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74  ted when the lat
9c20: 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  est connection t
9c30: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
9c40: 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69  * closes.  Setti
9c50: 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  ng persistent WA
9c60: 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68  L mode causes th
9c70: 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72  ose files to per
9c80: 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c  sist after.** cl
9c90: 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67  ose.  Persisting
9ca0: 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73   the files is us
9cb0: 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20  eful when other 
9cc0: 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64  processes that d
9cd0: 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72  o not.** have wr
9ce0: 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f  ite permission o
9cf0: 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20  n the directory 
9d00: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64  containing the d
9d10: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e  atabase file wan
9d20: 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65  t.** to read the
9d30: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
9d40: 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73  as the WAL and s
9d50: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
9d60: 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a  es must exist.**
9d70: 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68   in order for th
9d80: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65  e database to be
9d90: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
9da0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
9db0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
9dc0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
9dd0: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
9de0: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
9df0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
9e00: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
9e10: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
9e20: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  le persistent WA
9e30: 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  L mode or 1 to e
9e40: 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  nable persistent
9e50: 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49  .** WAL mode.  I
9e60: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
9e70: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
9e80: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
9e90: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
9ea0: 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20  WAL persistence 
9eb0: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
9ec0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9ed0: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
9ee0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
9ef0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
9f00: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
9f10: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
9f20: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
9f30: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
9f40: 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f  ent "powersafe-o
9f50: 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53  verwrite" or "PS
9f60: 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68  OW" setting.  Th
9f70: 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a  e PSOW setting.*
9f80: 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  * determines the
9f90: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
9fa0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
9fb0: 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a  TE] bit of the.*
9fc0: 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  * xDeviceCharact
9fd0: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73  eristics methods
9fe0: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  . The fourth par
9ff0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
a000: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
a010: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
a020: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
a030: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
a040: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
a050: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
a060: 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61   disable zero-da
a070: 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74  mage mode or 1 t
a080: 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61  o enable zero-da
a090: 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49  mage.** mode.  I
a0a0: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
a0b0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
a0c0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
a0d0: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
a0e0: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a0f0: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
a100: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
a110: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  TL_OVERWRITE]].*
a120: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a130: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20  CNTL_OVERWRITE] 
a140: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65  opcode is invoke
a150: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65  d by SQLite afte
a160: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77  r opening.** a w
a170: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  rite transaction
a180: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
a190: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20  t, unless it is 
a1a0: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20  rolled back for 
a1b0: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20  some.** reason, 
a1c0: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62  the entire datab
a1d0: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  ase file will be
a1e0: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20   overwritten by 
a1f0: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20  the current .** 
a200: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69  transaction. Thi
a210: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43  s is used by VAC
a220: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  UUM operations..
a230: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a240: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
a250: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
a260: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
a270: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20  ] opcode can be 
a280: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
a290: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61  he names of.** a
a2a0: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68  ll [VFSes] in th
a2b0: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68  e VFS stack.  Th
a2c0: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61  e names are of a
a2d0: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64  ll VFS shims and
a2e0: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f   the.** final bo
a2f0: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61  ttom-level VFS a
a300: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  re written into 
a310: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
a320: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
a330: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
a340: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74  the result is st
a350: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72  ored in the char
a360: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68  * variable.** th
a370: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  at the fourth pa
a380: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69  rameter of [sqli
a390: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a3a0: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a  ()] points to..*
a3b0: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20  * The caller is 
a3c0: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
a3d0: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f  freeing the memo
a3e0: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41  ry when done.  A
a3f0: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69  s with.** all fi
a400: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f  le-control actio
a410: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ns, there is no 
a420: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74  guarantee that t
a430: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c  his will actuall
a440: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67  y.** do anything
a450: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c  .  Callers shoul
a460: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  d initialize the
a470: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20   char* variable 
a480: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  to a NULL.** poi
a490: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69  nter in case thi
a4a0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
a4b0: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
a4c0: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f  d.  This file-co
a4d0: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65  ntrol.** is inte
a4e0: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73  nded for diagnos
a4f0: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a  tic use only..**
a500: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a510: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a  _FCNTL_PRAGMA]].
a520: 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b  ** ^Whenever a [
a530: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
a540: 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20  t is parsed, an 
a550: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a560: 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63  AGMA] .** file c
a570: 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74  ontrol is sent t
a580: 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69  o the open [sqli
a590: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
a5a0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
a5b0: 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  * to the databas
a5c0: 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20  e file to which 
a5d0: 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65  the pragma state
a5e0: 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68  ment refers. ^Th
a5f0: 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  e argument.** to
a600: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
a610: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
a620: 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72  control is an ar
a630: 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65  ray of.** pointe
a640: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63  rs to strings (c
a650: 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20  har**) in which 
a660: 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65  the second eleme
a670: 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a  nt of the array.
a680: 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
a690: 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64  f the pragma and
a6a0: 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65   the third eleme
a6b0: 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  nt is the argume
a6c0: 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61  nt to the.** pra
a6d0: 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  gma or NULL if t
a6e0: 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f  he pragma has no
a6f0: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65   argument.  ^The
a700: 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a   handler for an.
a710: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a720: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a730: 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e  ntrol can option
a740: 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69  ally make the fi
a750: 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f  rst element.** o
a760: 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67  f the char** arg
a770: 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61  ument point to a
a780: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
a790: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
a7a0: 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20  printf()].** or 
a7b0: 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61  the equivalent a
a7c0: 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77  nd that string w
a7d0: 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72  ill become the r
a7e0: 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61  esult of the pra
a7f0: 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72  gma or.** the er
a800: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74  ror message if t
a810: 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e  he pragma fails.
a820: 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
a830: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a840: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
a850: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e  eturns [SQLITE_N
a860: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e  OTFOUND], then n
a870: 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d  ormal .** [PRAGM
a880: 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f  A] processing co
a890: 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68  ntinues.  ^If th
a8a0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a8b0: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
a8c0: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
a8d0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65  [SQLITE_OK], the
a8e0: 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73  n the parser ass
a8f0: 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
a900: 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64   VFS has handled
a910: 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65   the PRAGMA itse
a920: 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65  lf and the parse
a930: 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f  r generates a no
a940: 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  -op.** prepared 
a950: 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 66 20  statement.  ^If 
a960: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
a970: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
a980: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a  ontrol returns.*
a990: 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64  * any result cod
a9a0: 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
a9b0: 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c  LITE_OK] or [SQL
a9c0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74  ITE_NOTFOUND], t
a9d0: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  hat means.** tha
a9e0: 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e  t the VFS encoun
a9f0: 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77  tered an error w
aa00: 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68  hile handling th
aa10: 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74  e [PRAGMA] and t
aa20: 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f  he.** compilatio
aa30: 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20  n of the PRAGMA 
aa40: 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72  fails with an er
aa50: 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  ror.  ^The [SQLI
aa60: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
aa70: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
aa80: 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62   occurs at the b
aa90: 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67  eginning of prag
aaa0: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61  ma statement ana
aab0: 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20  lysis and so.** 
aac0: 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76  it is able to ov
aad0: 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20  erride built-in 
aae0: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
aaf0: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nts..**.** <li>[
ab00: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
ab10: 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e  SYHANDLER]].** ^
ab20: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
ab30: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a  L_BUSYHANDLER].*
ab40: 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d  * file-control m
ab50: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79  ay be invoked by
ab60: 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64   SQLite on the d
ab70: 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e  atabase file han
ab80: 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61  dle.** shortly a
ab90: 66 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65  fter it is opene
aba0: 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  d in order to pr
abb0: 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56  ovide a custom V
abc0: 46 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a  FS with access.*
abd0: 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74  * to the connect
abe0: 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65  ions busy-handle
abf0: 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20  r callback. The 
ac00: 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74  argument is of t
ac10: 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a  ype (void **).**
ac20: 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74   - an array of t
ac30: 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75  wo (void *) valu
ac40: 65 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76  es. The first (v
ac50: 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20  oid *) actually 
ac60: 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66  points.** to a f
ac70: 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
ac80: 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29  (int (*)(void *)
ac90: 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69  ). In order to i
aca0: 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63  nvoke the connec
acb0: 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61  tions.** busy-ha
acc0: 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63  ndler, this func
acd0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69  tion should be i
ace0: 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20  nvoked with the 
acf0: 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20  second (void *) 
ad00: 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20  in.** the array 
ad10: 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75  as the only argu
ad20: 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75  ment. If it retu
ad30: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
ad40: 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  en the operation
ad50: 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
ad60: 74 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74  tried. If it ret
ad70: 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63  urns zero, the c
ad80: 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64  ustom VFS should
ad90: 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20   abandon the.** 
ada0: 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f  current operatio
adb0: 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  n..**.** <li>[[S
adc0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
add0: 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41  FILENAME]].** ^A
ade0: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69  pplication can i
adf0: 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54  nvoke the [SQLIT
ae00: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
ae10: 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72  NAME] file-contr
ae20: 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51  ol.** to have SQ
ae30: 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a  Lite generate a.
ae40: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
ae50: 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20  ename using the 
ae60: 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74  same algorithm t
ae70: 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20  hat is followed 
ae80: 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74  to generate.** t
ae90: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
aea0: 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c  es for TEMP tabl
aeb0: 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74  es and other int
aec0: 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65  ernal uses.  The
aed0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
aee0: 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20  uld be a char** 
aef0: 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69  which will be fi
af00: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69  lled with the fi
af10: 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65  lename.** writte
af20: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
af30: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
af40: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
af50: 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75   The caller shou
af60: 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71  ld.** invoke [sq
af70: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e  lite3_free()] on
af80: 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61   the result to a
af90: 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65  void a memory le
afa0: 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ak..**.** <li>[[
afb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
afc0: 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20  P_SIZE]].** The 
afd0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d  [SQLITE_FCNTL_MM
afe0: 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f  AP_SIZE] file co
aff0: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f  ntrol is used to
b000: 20 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68   query or set th
b010: 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  e.** maximum num
b020: 62 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61  ber of bytes tha
b030: 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66  t will be used f
b040: 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64  or memory-mapped
b050: 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67   I/O..** The arg
b060: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
b070: 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66  er to a value of
b080: 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e   type sqlite3_in
b090: 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61  t64 that.** is a
b0a0: 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d  n advisory maxim
b0b0: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  um number of byt
b0c0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74  es in the file t
b0d0: 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54  o memory map.  T
b0e0: 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73  he.** pointer is
b0f0: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
b100: 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e  h the old value.
b110: 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e    The limit is n
b120: 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a  ot changed if.**
b130: 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69   the value origi
b140: 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f  nally pointed to
b150: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e   is negative, an
b160: 64 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74  d so the current
b170: 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62   limit .** can b
b180: 65 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73  e queried by pas
b190: 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65  sing in a pointe
b1a0: 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20  r to a negative 
b1b0: 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a  number.  This.**
b1c0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
b1d0: 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
b1e0: 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50   to implement [P
b1f0: 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
b200: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b210: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
b220: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
b230: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66  E_FCNTL_TRACE] f
b240: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76  ile control prov
b250: 69 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e  ides advisory in
b260: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20  formation.** to 
b270: 74 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68  the VFS about wh
b280: 61 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61  at the higher la
b290: 79 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69  yers of the SQLi
b2a0: 74 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69  te stack are doi
b2b0: 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65  ng..** This file
b2c0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64   control is used
b2d0: 20 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74   by some VFS act
b2e0: 69 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73  ivity tracing [s
b2f0: 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72  hims]..** The ar
b300: 67 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f  gument is a zero
b310: 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
b320: 6e 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65  ng.  Higher laye
b330: 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c  rs in the.** SQL
b340: 69 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65  ite stack may ge
b350: 6e 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73  nerate instances
b360: 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f   of this file co
b370: 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20  ntrol if.** the 
b380: 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54  [SQLITE_USE_FCNT
b390: 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65  L_TRACE] compile
b3a0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
b3b0: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  enabled..**.** <
b3c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b3d0: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a  L_HAS_MOVED]].**
b3e0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
b3f0: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69  TL_HAS_MOVED] fi
b400: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72  le control inter
b410: 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65  prets its argume
b420: 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  nt as a.** point
b430: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
b440: 20 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61   and it writes a
b450: 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68   boolean into th
b460: 61 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e  at integer depen
b470: 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  ding.** on wheth
b480: 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69  er or not the fi
b490: 6c 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61  le has been rena
b4a0: 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64  med, moved, or d
b4b0: 65 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a  eleted since it.
b4c0: 2a 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65  ** was first ope
b4d0: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ned..**.** <li>[
b4e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
b4f0: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d  N32_SET_HANDLE]]
b500: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b510: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
b520: 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69  HANDLE] opcode i
b530: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
b540: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
b550: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
b560: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
b570: 74 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65  thod to swap the
b580: 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74   file handle wit
b590: 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69  h the one.** poi
b5a0: 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70  nted to by the p
b5b0: 41 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54  Arg argument.  T
b5c0: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69  his capability i
b5d0: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
b5e0: 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  sting.** and onl
b5f0: 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75  y needs to be su
b600: 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c  pported when SQL
b610: 49 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69  ITE_TEST is defi
b620: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e  ned..**.** </ul>
b630: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
b640: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
b650: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
b660: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
b670: 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_GET_LOCKPROXYF
b680: 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ILE             
b690: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
b6a0: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
b6b0: 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 33  LE             3
b6c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b6d0: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
b6e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a                4.
b6f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b700: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20  CNTL_SIZE_HINT  
b710: 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
b720: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b730: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20  NTL_CHUNK_SIZE  
b740: 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
b750: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b760: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20  TL_FILE_POINTER 
b770: 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
b780: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b790: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20  L_SYNC_OMITTED  
b7a0: 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66            8.#def
b7b0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b7c0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20  _WIN32_AV_RETRY 
b7d0: 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
b7e0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b7f0: 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20  PERSIST_WAL     
b800: 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e         10.#defin
b810: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  e SQLITE_FCNTL_O
b820: 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20  VERWRITE        
b830: 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65        11.#define
b840: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46   SQLITE_FCNTL_VF
b850: 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  SNAME           
b860: 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20       12.#define 
b870: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
b880: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
b890: 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53      13.#define S
b8a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b8b0: 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
b8c0: 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51     14.#define SQ
b8d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
b8e0: 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20  ANDLER          
b8f0: 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c    15.#define SQL
b900: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
b910: 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  LENAME          
b920: 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   16.#define SQLI
b930: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
b940: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
b950: 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  18.#define SQLIT
b960: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20  E_FCNTL_TRACE   
b970: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
b980: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
b990: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
b9a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
b9b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b9c0: 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20  FCNTL_SYNC      
b9d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 0a               21.
b9e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b9f0: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
ba00: 45 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23  ETWO        22.#
ba10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ba20: 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41  NTL_WIN32_SET_HA
ba30: 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a 0a 2f  NDLE       23../
ba40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
ba50: 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  utex Handle.**.*
ba60: 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75  * The mutex modu
ba70: 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65  le within SQLite
ba80: 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65   defines [sqlite
ba90: 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61  3_mutex] to be a
baa0: 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79  n.** abstract ty
bab0: 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f  pe for a mutex o
bac0: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69  bject.  The SQLi
bad0: 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f  te core never lo
bae0: 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e  oks.** at the in
baf0: 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
bb00: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c  ation of an [sql
bb10: 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74  ite3_mutex].  It
bb20: 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77   only.** deals w
bb30: 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ith pointers to 
bb40: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
bb50: 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  ex] object..**.*
bb60: 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72  * Mutexes are cr
bb70: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  eated using [sql
bb80: 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
bb90: 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
bba0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
bbb0: 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74  utex sqlite3_mut
bbc0: 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ex;../*.** CAPI3
bbd0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
bbe0: 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41  e Object.**.** A
bbf0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
bc00: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
bc10: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
bc20: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
bc30: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65  en.** the SQLite
bc40: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e   core and the un
bc50: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
bc60: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20  ng system.  The 
bc70: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20  "vfs".** in the 
bc80: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65  name of the obje
bc90: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76  ct stands for "v
bca0: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
bcb0: 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65  em".  See.** the
bcc0: 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75   [VFS | VFS docu
bcd0: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66  mentation] for f
bce0: 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69  urther informati
bcf0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  on..**.** The va
bd00: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
bd10: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
bd20: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
bd30: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
bd40: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
bd50: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
bd60: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
bd70: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
bd80: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
bd90: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
bda0: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
bdb0: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61  eased.  Note tha
bdc0: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a  t the structure.
bdd0: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
bde0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61  3_vfs object cha
bdf0: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e  nges in the tran
be00: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  saction between.
be10: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
be20: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e  n 3.5.9 and 3.6.
be30: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  0 and yet the iV
be40: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
be50: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   not.** modified
be60: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
be70: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
be80: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
be90: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
bea0: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
beb0: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
bec0: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
bed0: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
bee0: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
bef0: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
bf00: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
bf10: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
bf20: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
bf30: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
bf40: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
bf50: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
bf60: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
bf70: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
bf80: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
bf90: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
bfa0: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
bfb0: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
bfc0: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
bfd0: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
bfe0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
bff0: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
c000: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
c010: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
c020: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
c030: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
c040: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
c050: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
c060: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
c070: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
c080: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
c090: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
c0a0: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
c0b0: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
c0c0: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
c0d0: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
c0e0: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
c0f0: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
c100: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
c110: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
c120: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
c130: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
c140: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
c150: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
c160: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
c170: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
c180: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
c190: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
c1a0: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
c1b0: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
c1c0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
c1d0: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
c1e0: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
c1f0: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
c200: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
c210: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
c220: 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20  _vfs.xOpen]].** 
c230: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
c240: 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  es that the zFil
c250: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
c260: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
c270: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
c280: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
c290: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
c2a0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20  xFullPathname() 
c2b0: 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c  with an optional
c2c0: 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a   suffix added..*
c2d0: 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69  * ^If a suffix i
c2e0: 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a  s added to the z
c2f0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
c300: 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63  er, it will.** c
c310: 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67  onsist of a sing
c320: 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  le "-" character
c330: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20   followed by no 
c340: 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20  more than.** 11 
c350: 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64  alphanumeric and
c360: 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65  /or "-" characte
c370: 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66  rs..** ^SQLite f
c380: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
c390: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
c3a0: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
c3b0: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
c3c0: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
c3d0: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
c3e0: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
c3f0: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
c400: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
c410: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
c420: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
c430: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
c440: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
c450: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
c460: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
c470: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
c480: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
c490: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
c4a0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
c4b0: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
c4c0: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
c4d0: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
c4e0: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
c4f0: 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65  .  ^Whenever the
c500: 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70   .** xFilename p
c510: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
c520: 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65   it will also be
c530: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
c540: 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61  he.** flags para
c550: 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75  meter will inclu
c560: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
c570: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a  DELETEONCLOSE]..
c580: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
c590: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
c5a0: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  n() includes all
c5b0: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20   bits set in.** 
c5c0: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
c5d0: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
c5e0: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69  pen_v2()].  Or i
c5f0: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
c600: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
c610: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
c620: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
c630: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73  includes at leas
c640: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  t.** [SQLITE_OPE
c650: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
c660: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
c670: 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65  TE]. .** If xOpe
c680: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65  n() opens a file
c690: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20   read-only then 
c6a0: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61  it sets *pOutFla
c6b0: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65  gs to.** include
c6c0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
c6d0: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20  ADONLY].  Other 
c6e0: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61  bits in *pOutFla
c6f0: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a  gs may be set..*
c700: 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69  *.** ^(SQLite wi
c710: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
c720: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
c730: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
c740: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
c750: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
c760: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
c770: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ned:.**.** <ul>.
c780: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
c790: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
c7a0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
c7b0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
c7c0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
c7d0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
c7e0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
c7f0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
c800: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
c810: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
c820: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
c830: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
c840: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
c850: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
c860: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
c870: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
c880: 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20  TE_OPEN_WAL].** 
c890: 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
c8a0: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
c8b0: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
c8c0: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
c8d0: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
c8e0: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
c8f0: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
c900: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
c910: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
c920: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
c930: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
c940: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
c950: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
c960: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
c970: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
c980: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
c990: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
c9a0: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
c9b0: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
c9c0: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
c9d0: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
c9e0: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
c9f0: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
ca00: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
ca10: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
ca20: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
ca30: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
ca40: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
ca50: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
ca60: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
ca70: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
ca80: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
ca90: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
caa0: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
cab0: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
cac0: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
cad0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
cae0: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
caf0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
cb00: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
cb10: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
cb20: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
cb30: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
cb40: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
cb50: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
cb60: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
cb70: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
cb80: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
cb90: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
cba0: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
cbb0: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
cbc0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
cbd0: 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  SE].** will be s
cbe0: 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61  et for TEMP data
cbf0: 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20  bases and their 
cc00: 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69  journals, transi
cc10: 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73  ent.** databases
cc20: 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c  , and subjournal
cc30: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  s..**.** ^The [S
cc40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
cc50: 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c  SIVE] flag is al
cc60: 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e  ways used in con
cc70: 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  junction.** with
cc80: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
cc90: 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20  N_CREATE] flag, 
cca0: 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64  which are both d
ccb0: 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f  irectly.** analo
ccc0: 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58  gous to the O_EX
ccd0: 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66  CL and O_CREAT f
cce0: 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49  lags of the POSI
ccf0: 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e  X open().** API.
cd00: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45    The SQLITE_OPE
cd10: 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  N_EXCLUSIVE flag
cd20: 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69  , when paired wi
cd30: 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
cd40: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69  E_OPEN_CREATE, i
cd50: 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  s used to indica
cd60: 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f  te that file sho
cd70: 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  uld always.** be
cd80: 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68   created, and th
cd90: 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f  at it is an erro
cda0: 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20  r if it already 
cdb0: 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73  exists..** It is
cdc0: 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64   <i>not</i> used
cdd0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65   to indicate the
cde0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
cdf0: 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65  opened .** for e
ce00: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e  xclusive access.
ce10: 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74  .**.** ^At least
ce20: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
ce30: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
ce40: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
ce50: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
ce60: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
ce70: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
ce80: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
ce90: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
cea0: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
ceb0: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
cec0: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
ced0: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
cee0: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
cef0: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
cf00: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
cf10: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
cf20: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
cf30: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
cf40: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
cf50: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
cf60: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
cf70: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
cf80: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
cf90: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
cfa0: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
cfb0: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
cfc0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
cfd0: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
cfe0: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
cff0: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
d000: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
d010: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
d020: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
d030: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
d040: 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  l..**.** [[sqlit
d050: 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d  e3_vfs.xAccess]]
d060: 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61  .** ^The flags a
d070: 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65  rgument to xAcce
d080: 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c  ss() may be [SQL
d090: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
d0a0: 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f  S].** to test fo
d0b0: 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20  r the existence 
d0c0: 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53  of a file, or [S
d0d0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
d0e0: 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65  DWRITE] to.** te
d0f0: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
d100: 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e  e is readable an
d110: 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b  d writable, or [
d120: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
d130: 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77  AD].** to test w
d140: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
d150: 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62   at least readab
d160: 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63  le.   The file c
d170: 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63  an be a.** direc
d180: 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  tory..**.** ^SQL
d190: 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
d1a0: 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
d1b0: 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
d1c0: 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ytes for the.** 
d1d0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46  output buffer xF
d1e0: 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68  ullPathname.  Th
d1f0: 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20  e exact size of 
d200: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
d210: 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73  r.** is also pas
d220: 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74  sed as a paramet
d230: 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68  er to both  meth
d240: 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70  ods. If the outp
d250: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
d260: 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68  not large enough
d270: 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  , [SQLITE_CANTOP
d280: 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65  EN] should be re
d290: 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68  turned. Since th
d2a0: 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64  is is.** handled
d2b0: 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f   as a fatal erro
d2c0: 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73  r by SQLite, vfs
d2d0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
d2e0: 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72   should endeavor
d2f0: 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74  .** to prevent t
d300: 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d  his by setting m
d310: 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73  xPathname to a s
d320: 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67  ufficiently larg
d330: 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  e value..**.** T
d340: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
d350: 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72  , xSleep(), xCur
d360: 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20  rentTime(), and 
d370: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
d380: 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  4().** interface
d390: 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  s are not strict
d3a0: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
d3b0: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
d3c0: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
d3d0: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
d3e0: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
d3f0: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
d400: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
d410: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
d420: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
d430: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
d440: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
d450: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
d460: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
d470: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
d480: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
d490: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
d4a0: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a  ness obtained..*
d4b0: 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d  * The xSleep() m
d4c0: 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65  ethod causes the
d4d0: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
d4e0: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
d4f0: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
d500: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
d510: 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65  nds given.  ^The
d520: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
d530: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
d540: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
d550: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
d560: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74  rrent date and t
d570: 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61  ime as.** a floa
d580: 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
d590: 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65  ..** ^The xCurre
d5a0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
d5b0: 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73  thod returns, as
d5c0: 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
d5d0: 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e   Julian.** Day N
d5e0: 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64  umber multiplied
d5f0: 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68   by 86400000 (th
d600: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
d610: 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20  iseconds in .** 
d620: 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20  a 24-hour day). 
d630: 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c   .** ^SQLite wil
d640: 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65  l use the xCurre
d650: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
d660: 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20  thod to get the 
d670: 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20  current.** date 
d680: 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74  and time if that
d690: 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c   method is avail
d6a0: 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f  able (if iVersio
d6b0: 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72  n is 2 or .** gr
d6c0: 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75  eater and the fu
d6d0: 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
d6e0: 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20  s not NULL) and 
d6f0: 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a  will fall back.*
d700: 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d  * to xCurrentTim
d710: 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54  e() if xCurrentT
d720: 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e  imeInt64() is un
d730: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  available..**.**
d740: 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d   ^The xSetSystem
d750: 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74  Call(), xGetSyst
d760: 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e  emCall(), and xN
d770: 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20  estSystemCall() 
d780: 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
d790: 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68  e not used by th
d7a0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20  e SQLite core.  
d7b0: 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69  These optional i
d7c0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72  nterfaces are pr
d7d0: 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d  ovided.** by som
d7e0: 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c  e VFSes to facil
d7f0: 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66  itate testing of
d800: 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42   the VFS code. B
d810: 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a  y overriding .**
d820: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69   system calls wi
d830: 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64  th functions und
d840: 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20  er its control, 
d850: 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63  a test program c
d860: 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66  an.** simulate f
d870: 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20  aults and error 
d880: 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20  conditions that 
d890: 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20  would otherwise 
d8a0: 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20  be difficult.** 
d8b0: 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f  or impossible to
d8c0: 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65   induce.  The se
d8d0: 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c  t of system call
d8e0: 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  s that can be ov
d8f0: 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69  erridden.** vari
d900: 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20  es from one VFS 
d910: 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20  to another, and 
d920: 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e  from one version
d930: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53   of the same VFS
d940: 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e   to the.** next.
d950: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
d960: 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e  hat use these in
d970: 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65  terfaces must be
d980: 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e   prepared for an
d990: 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74  y.** or all of t
d9a0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
d9b0: 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f  to be NULL or fo
d9c0: 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72  r their behavior
d9d0: 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72   to change.** fr
d9e0: 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74  om one release t
d9f0: 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70  o the next.  App
da00: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e  lications must n
da10: 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  ot attempt to ac
da20: 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74  cess.** any of t
da30: 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20  hese methods if 
da40: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20  the iVersion of 
da50: 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20  the VFS is less 
da60: 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64  than 3..*/.typed
da70: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
da80: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
da90: 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  s;.typedef void 
daa0: 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  (*sqlite3_syscal
dab0: 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74  l_ptr)(void);.st
dac0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
dad0: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
dae0: 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  n;            /*
daf0: 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69   Structure versi
db00: 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65  on number (curre
db10: 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74  ntly 3) */.  int
db20: 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20   szOsFile;      
db30: 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66        /* Size of
db40: 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69   subclassed sqli
db50: 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e  te3_file */.  in
db60: 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20  t mxPathname;   
db70: 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
db80: 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  m file pathname 
db90: 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69  length */.  sqli
dba0: 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20  te3_vfs *pNext; 
dbb0: 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67       /* Next reg
dbc0: 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20  istered VFS */. 
dbd0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
dbe0: 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  me;       /* Nam
dbf0: 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61  e of this virtua
dc00: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f  l file system */
dc10: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
dc20: 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50  a;          /* P
dc30: 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63  ointer to applic
dc40: 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64  ation-specific d
dc50: 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ata */.  int (*x
dc60: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
dc70: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
dc80: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66  zName, sqlite3_f
dc90: 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  ile*,.          
dca0: 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20       int flags, 
dcb0: 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b  int *pOutFlags);
dcc0: 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65  .  int (*xDelete
dcd0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
dce0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
dcf0: 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b  e, int syncDir);
dd00: 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73  .  int (*xAccess
dd10: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
dd20: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
dd30: 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e  e, int flags, in
dd40: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
dd50: 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61  nt (*xFullPathna
dd60: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
dd70: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
dd80: 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63  ame, int nOut, c
dd90: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f  har *zOut);.  vo
dda0: 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73  id *(*xDlOpen)(s
ddb0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
ddc0: 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
ddd0: 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  me);.  void (*xD
dde0: 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  lError)(sqlite3_
ddf0: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
de00: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
de10: 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53  .  void (*(*xDlS
de20: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
de30: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
de40: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f  ar *zSymbol))(vo
de50: 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  id);.  void (*xD
de60: 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
de70: 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
de80: 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
de90: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
dea0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
deb0: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
dec0: 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
ded0: 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
dee0: 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
def0: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
df00: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
df10: 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  uble*);.  int (*
df20: 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73  xGetLastError)(s
df30: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
df40: 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a  , char *);.  /*.
df50: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
df60: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
df70: 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73  rsion 1 of the s
df80: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
df90: 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e  .  ** definition
dfa0: 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f  .  Those that fo
dfb0: 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69  llow are added i
dfc0: 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c  n version 2 or l
dfd0: 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ater.  */.  int 
dfe0: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  (*xCurrentTimeIn
dff0: 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73  t64)(sqlite3_vfs
e000: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
e010: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
e020: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
e030: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
e040: 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73  1 and 2 of the s
e050: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
e060: 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c  ..  ** Those bel
e070: 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69  ow are for versi
e080: 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72  on 3 and greater
e090: 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ..  */.  int (*x
e0a0: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  SetSystemCall)(s
e0b0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
e0c0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
e0d0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
e0e0: 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f  ptr);.  sqlite3_
e0f0: 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47  syscall_ptr (*xG
e100: 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
e110: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
e120: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
e130: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a    const char *(*
e140: 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29  xNextSystemCall)
e150: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
e160: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
e170: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
e180: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
e190: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
e1a0: 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68   through 3 of th
e1b0: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
e1c0: 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69  ect..  ** New fi
e1d0: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
e1e0: 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76  nded in figure v
e1f0: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
e200: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
e210: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
e220: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
e230: 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b  appens. .  */.};
e240: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
e250: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
e260: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
e270: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
e280: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
e290: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
e2a0: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
e2b0: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
e2c0: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
e2d0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
e2e0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64   object.  They d
e2f0: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
e300: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
e310: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
e320: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
e330: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
e340: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
e350: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
e360: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
e370: 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
e380: 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
e390: 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
e3a0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
e3b0: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
e3c0: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
e3d0: 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d   whether the nam
e3e0: 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20  ed directory is 
e3f0: 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e  both readable an
e400: 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69  d writable.** (i
e410: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
e420: 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61  f files can be a
e430: 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61  dded, removed, a
e440: 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69  nd renamed withi
e450: 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f  n.** the directo
e460: 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ry)..** The SQLI
e470: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
e480: 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20  ITE constant is 
e490: 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f  currently used o
e4a0: 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74  nly by the.** [t
e4b0: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
e4c0: 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f  ory pragma], tho
e4d0: 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63  ugh this could c
e4e0: 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
e4f0: 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
e500: 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20  SQLite..** With 
e510: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
e520: 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  AD, the xAccess 
e530: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
e540: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
e550: 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20  e is readable.  
e560: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
e570: 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20  S_READ constant 
e580: 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  is.** currently 
e590: 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69  unused, though i
e5a0: 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20  t might be used 
e5b0: 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65  in a future rele
e5c0: 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
e5d0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
e5e0: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
e5f0: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
e600: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
e610: 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73  DWRITE 1   /* Us
e620: 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d  ed by PRAGMA tem
e630: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
e640: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
e650: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
e660: 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73       2   /* Unus
e670: 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
e680: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
e690: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46   the xShmLock VF
e6a0: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
e6b0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
e6c0: 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68  stants define th
e6d0: 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e  e various lockin
e6e0: 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  g operations.** 
e6f0: 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78  allowed by the x
e700: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
e710: 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  f [sqlite3_io_me
e720: 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20  thods].  The.** 
e730: 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68  following are th
e740: 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d  e only legal com
e750: 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61  binations of fla
e760: 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68  gs to the.** xSh
e770: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a  mLock method:.**
e780: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
e790: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
e7a0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
e7b0: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
e7c0: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
e7d0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
e7e0: 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53  USIVE.** <li>  S
e7f0: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
e800: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
e810: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
e820: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
e830: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
e840: 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a  LUSIVE.** </ul>.
e850: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63  **.** When unloc
e860: 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53  king, the same S
e870: 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49  HARED or EXCLUSI
e880: 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20  VE flag must be 
e890: 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77  supplied as.** w
e8a0: 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20  as given no the 
e8b0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f  corresponding lo
e8c0: 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ck.  .**.** The 
e8d0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
e8e0: 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  can transition b
e8f0: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
e900: 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a  and SHARED or.**
e910: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
e920: 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  d and EXCLUSIVE.
e930: 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e    It cannot tran
e940: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53  sition between S
e950: 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43  HARED.** and EXC
e960: 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69  LUSIVE..*/.#defi
e970: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  ne SQLITE_SHM_UN
e980: 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65  LOCK       1.#de
e990: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
e9a0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23  LOCK         2.#
e9b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
e9c0: 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34  M_SHARED       4
e9d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e9e0: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20  SHM_EXCLUSIVE   
e9f0: 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   8../*.** CAPI3R
ea00: 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d  EF: Maximum xShm
ea10: 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a  Lock index.**.**
ea20: 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
ea30: 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33  thod on [sqlite3
ea40: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79  _io_methods] may
ea50: 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62   use values.** b
ea60: 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69  etween 0 and thi
ea70: 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73  s upper bound as
ea80: 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72   its "offset" ar
ea90: 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53  gument..** The S
eaa0: 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20  QLite core will 
eab0: 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f  never attempt to
eac0: 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65   acquire or rele
ead0: 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75  ase a.** lock ou
eae0: 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61  tside of this ra
eaf0: 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge.*/.#define S
eb00: 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20  QLITE_SHM_NLOCK 
eb10: 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a         8.../*.**
eb20: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69   CAPI3REF: Initi
eb30: 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65  alize The SQLite
eb40: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e   Library.**.** ^
eb50: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
eb60: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
eb70: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
eb80: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
eb90: 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ry.  ^The sqlite
eba0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75  3_shutdown() rou
ebb0: 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  tine.** dealloca
ebc0: 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65  tes any resource
ebd0: 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f  s that were allo
ebe0: 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
ebf0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
ec00: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
ec10: 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f   are designed to
ec20: 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20   aid in process 
ec30: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
ec40: 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f  nd.** shutdown o
ec50: 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65  n embedded syste
ec60: 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e  ms.  Workstation
ec70: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73   applications us
ec80: 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f  ing.** SQLite no
ec90: 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65  rmally do not ne
eca0: 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74  ed to invoke eit
ecb0: 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75  her of these rou
ecc0: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  tines..**.** A c
ecd0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
ece0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
ecf0: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
ed00: 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
ed10: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
ed20: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ed30: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
ed40: 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
ed50: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
ed60: 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
ed70: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
ed80: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ed90: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
eda0: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
edb0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
edc0: 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e  hutdown().  ^(On
edd0: 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ly an effective 
ede0: 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  call.** of sqlit
edf0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
ee00: 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c  does any initial
ee10: 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74  ization.  All ot
ee20: 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65  her calls.** are
ee30: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
ee40: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  .)^.**.** A call
ee50: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
ee60: 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66  down() is an "ef
ee70: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
ee80: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
ee90: 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  .** call to sqli
eea0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73  te3_shutdown() s
eeb0: 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71  ince the last sq
eec0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
eed0: 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61  ().  ^(Only.** a
eee0: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
eef0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
ef00: 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20  down() does any 
ef10: 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  deinitialization
ef20: 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76  ..** All other v
ef30: 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71  alid calls to sq
ef40: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
ef50: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
ef60: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  -ops.)^.**.** Th
ef70: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
ef80: 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65  lize() interface
ef90: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20   is threadsafe, 
efa0: 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  but sqlite3_shut
efb0: 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74  down().** is not
efc0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  .  The sqlite3_s
efd0: 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66  hutdown() interf
efe0: 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65  ace must only be
eff0: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a   called from a.*
f000: 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  * single thread.
f010: 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61    All open [data
f020: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
f030: 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64  ] must be closed
f040: 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65   and all.** othe
f050: 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63  r SQLite resourc
f060: 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c  es must be deall
f070: 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20  ocated prior to 
f080: 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69  invoking.** sqli
f090: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a  te3_shutdown()..
f0a0: 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65  **.** Among othe
f0b0: 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74  r things, ^sqlit
f0c0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f0d0: 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  will invoke.** s
f0e0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
f0f0: 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73  .  Similarly, ^s
f100: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f110: 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ).** will invoke
f120: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
f130: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
f140: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f150: 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
f160: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  ns [SQLITE_OK] o
f170: 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49  n success..** ^I
f180: 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  f for some reaso
f190: 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  n, sqlite3_initi
f1a0: 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c  alize() is unabl
f1b0: 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a  e to initialize.
f1c0: 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28  ** the library (
f1d0: 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e  perhaps it is un
f1e0: 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
f1f0: 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72   a needed resour
f200: 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20  ce such.** as a 
f210: 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e  mutex) it return
f220: 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  s an [error code
f230: 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  ] other than [SQ
f240: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
f250: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
f260: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
f270: 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
f280: 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
f290: 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
f2a0: 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
f2b0: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
f2c0: 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
f2d0: 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
f2e0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
f2f0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
f300: 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
f310: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
f320: 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
f330: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f340: 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
f350: 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
f360: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
f370: 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
f380: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
f390: 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
f3a0: 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
f3b0: 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
f3c0: 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69  dy.  ^However, i
f3d0: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
f3e0: 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53  iled with the [S
f3f0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
f400: 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  NIT].** compile-
f410: 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65  time option, the
f420: 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  n the automatic 
f430: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
f440: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
f450: 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64   are omitted and
f460: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
f470: 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74   must call sqlit
f480: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f490: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f  directly.** prio
f4a0: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
f4b0: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
f4c0: 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69  rface.  For maxi
f4d0: 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c  mum portability,
f4e0: 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  .** it is recomm
f4f0: 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
f500: 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69  cations always i
f510: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
f520: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69  itialize().** di
f530: 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20  rectly prior to 
f540: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
f550: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
f560: 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73  .  Future releas
f570: 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  es.** of SQLite 
f580: 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73  may require this
f590: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
f5a0: 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  s, the behavior 
f5b0: 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65  exhibited.** whe
f5c0: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
f5d0: 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
f5e0: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
f5f0: 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68   might become th
f600: 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68  e.** default beh
f610: 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75  avior in some fu
f620: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20  ture release of 
f630: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
f640: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
f650: 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  t() routine does
f660: 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
f670: 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e  m specific.** in
f680: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
f690: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
f6a0: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
f6b0: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75  _os_end().** rou
f6c0: 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
f6d0: 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65  effect of sqlite
f6e0: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79  3_os_init().  Ty
f6f0: 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70  pical tasks.** p
f700: 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73  erformed by thes
f710: 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75  e routines inclu
f720: 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72  de allocation or
f730: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
f740: 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75   of static resou
f750: 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61  rces, initializa
f760: 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76  tion of global v
f770: 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74  ariables,.** set
f780: 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c  ting up a defaul
f790: 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
f7a0: 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69  module, or setti
f7b0: 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75  ng up.** a defau
f7c0: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
f7d0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
f7e0: 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  config()]..**.**
f7f0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
f800: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e   should never in
f810: 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69  voke either sqli
f820: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
f830: 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
f840: 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  nd() directly.  
f850: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
f860: 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f  should only invo
f870: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  ke.** sqlite3_in
f880: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73  itialize() and s
f890: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f8a0: 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ).  The sqlite3_
f8b0: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74  os_init().** int
f8c0: 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64  erface is called
f8d0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
f8e0: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
f8f0: 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71  lize() and.** sq
f900: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69  lite3_os_end() i
f910: 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69  s called by sqli
f920: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
f930: 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   Appropriate.** 
f940: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
f950: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  for sqlite3_os_i
f960: 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
f970: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72  3_os_end().** ar
f980: 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  e built into SQL
f990: 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63  ite when it is c
f9a0: 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78  ompiled for Unix
f9b0: 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53  , Windows, or OS
f9c0: 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73  /2..** When [cus
f9d0: 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69  tom builds | bui
f9e0: 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61  lt for other pla
f9f0: 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e  tforms].** (usin
fa00: 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53  g the [SQLITE_OS
fa10: 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c  _OTHER=1] compil
fa20: 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
fa30: 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  ) the applicatio
fa40: 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
fa50: 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
fa60: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73  ntation for.** s
fa70: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
fa80: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
fa90: 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69  end().  An appli
faa0: 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a  cation-supplied.
fab0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
fac0: 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  n of sqlite3_os_
fad0: 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65  init() or sqlite
fae0: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75  3_os_end().** mu
faf0: 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  st return [SQLIT
fb00: 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
fb10: 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20   and some other 
fb20: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
fb30: 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f  n.** failure..*/
fb40: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69  .int sqlite3_ini
fb50: 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69  tialize(void);.i
fb60: 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nt sqlite3_shutd
fb70: 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  own(void);.int s
fb80: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76  qlite3_os_init(v
fb90: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
fba0: 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a  3_os_end(void);.
fbb0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
fbc0: 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65   Configuring The
fbd0: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
fbe0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
fbf0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
fc00: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
fc10: 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66  make global conf
fc20: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
fc30: 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69  nges to SQLite i
fc40: 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20  n order to tune 
fc50: 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70  SQLite to the sp
fc60: 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a  ecific needs of.
fc70: 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
fc80: 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  on.  The default
fc90: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69   configuration i
fca0: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
fcb0: 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  r most.** applic
fcc0: 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68  ations and so th
fcd0: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
fce0: 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73  ually not necess
fcf0: 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70  ary.  It is.** p
fd00: 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f  rovided to suppo
fd10: 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74  rt rare applicat
fd20: 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61  ions with unusua
fd30: 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  l needs..**.** T
fd40: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
fd50: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
fd60: 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
fd70: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
fd80: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65  n.** must insure
fd90: 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
fda0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
fdb0: 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
fdc0: 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
fdd0: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
fde0: 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
fdf0: 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65  ng.  Furthermore
fe00: 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
fe10: 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ().** may only b
fe20: 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20  e invoked prior 
fe30: 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69  to library initi
fe40: 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a  alization using.
fe50: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ** [sqlite3_init
fe60: 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  ialize()] or aft
fe70: 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b  er shutdown by [
fe80: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fe90: 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ()]..** ^If sqli
fea0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
feb0: 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
fec0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fed0: 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a  ()] and before.*
fee0: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
fef0: 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77  own()] then it w
ff00: 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54  ill return SQLIT
ff10: 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74  E_MISUSE..** Not
ff20: 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74  e, however, that
ff30: 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   ^sqlite3_config
ff40: 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  () can be called
ff50: 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   as part of the.
ff60: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
ff70: 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74  n of an applicat
ff80: 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c  ion-defined [sql
ff90: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e  ite3_os_init()].
ffa0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
ffb0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
ffc0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
ffd0: 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   an integer.** [
ffe0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
fff0: 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72  tion] that deter
10000 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72  mines.** what pr
10010 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65  operty of SQLite
10020 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67   is to be config
10030 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e  ured.  Subsequen
10040 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76  t arguments.** v
10050 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
10060 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74   the [configurat
10070 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** i
10080 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
10090 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  ment..**.** ^Whe
100a0 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  n a configuratio
100b0 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c  n option is set,
100c0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
100d0 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ) returns [SQLIT
100e0 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  E_OK]..** ^If th
100f0 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e  e option is unkn
10100 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73  own or SQLite is
10110 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74   unable to set t
10120 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65  he option.** the
10130 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  n this routine r
10140 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72  eturns a non-zer
10150 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  o [error code]..
10160 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
10170 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
10180 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10190 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
101a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
101b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
101c0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
101d0 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
101e0 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
101f0 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
10200 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
10210 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
10220 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
10230 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
10240 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
10250 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
10260 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
10270 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
10280 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10290 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
102a0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
102b0 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment)..**.** The
102c0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
102d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
102e0 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
102f0 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  is the.** [SQLIT
10300 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
10310 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61  SIDE | configura
10320 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20  tion verb] - an 
10330 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a  integer code .**
10340 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
10350 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74  what aspect of t
10360 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
10370 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
10380 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
10390 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
103a0 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e  ments vary depen
103b0 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66  ding on the conf
103c0 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a  iguration verb..
103d0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  **.** ^Calls to 
103e0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
103f0 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  g() return SQLIT
10400 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79  E_OK if and only
10410 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20   if.** the call 
10420 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75  is considered su
10430 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  ccessful..*/.int
10440 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
10450 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ig(sqlite3*, int
10460 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a   op, ...);../*.*
10470 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
10480 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
10490 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20  utines.**.** An 
104a0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
104b0 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
104c0 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
104d0 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
104e0 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
104f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10500 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
10510 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
10520 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
10530 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
10540 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
10550 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
10560 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
10570 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
10580 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
10590 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
105a0 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
105b0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
105c0 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
105d0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72  ONFIG_MALLOC] or
105e0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
105f0 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a  GETMALLOC].  .**
10600 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
10610 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
10620 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
10630 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
10640 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
10650 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
10660 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20  LOC]).** during 
10670 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
10680 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61  n application ca
10690 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  n specify an alt
106a0 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
106b0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
106c0 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69  bsystem for SQLi
106d0 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c  te to use for al
106e0 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61  l of its.** dyna
106f0 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
10700 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
10710 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
10720 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69  ith several [bui
10730 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
10740 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74  ocators].** that
10750 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61   are perfectly a
10760 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20  dequate for the 
10770 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a  overwhelming maj
10780 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
10790 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61  tions.** and tha
107a0 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  t this object is
107b0 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20   only useful to 
107c0 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20  a tiny minority 
107d0 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
107e0 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69  ** with speciali
107f0 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  zed memory alloc
10800 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e  ation requiremen
10810 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ts.  This object
10820 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64   is.** also used
10830 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
10840 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  of SQLite in ord
10850 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e  er to specify an
10860 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
10870 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
10880 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20   that simulates 
10890 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65  memory out-of-me
108a0 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20  mory conditions 
108b0 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76  in.** order to v
108c0 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74  erify that SQLit
108d0 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65  e recovers grace
108e0 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a  fully from such.
108f0 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a  ** conditions..*
10900 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63  *.** The xMalloc
10910 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20  , xRealloc, and 
10920 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75  xFree methods mu
10930 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65  st work like the
10940 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65  .** malloc(), re
10950 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
10960 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f  () functions fro
10970 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
10980 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51   library..** ^SQ
10990 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
109a0 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
109b0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78  argument to.** x
109c0 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79  Realloc is alway
109d0 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e  s a value return
109e0 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61  ed by a prior ca
109f0 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a  ll to xRoundup..
10a00 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
10a10 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
10a20 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
10a30 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
10a40 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
10a50 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
10a60 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
10a70 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
10a80 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
10a90 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
10aa0 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
10ab0 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
10ac0 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
10ad0 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
10ae0 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
10af0 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
10b00 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
10b10 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
10b20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
10b30 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
10b40 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
10b50 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
10b60 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
10b70 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
10b80 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
10b90 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
10ba0 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
10bb0 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
10bc0 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
10bd0 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
10be0 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
10bf0 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
10c00 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
10c10 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
10c20 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
10c30 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
10c40 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
10c50 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
10c60 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
10c70 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
10c80 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
10c90 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
10ca0 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
10cb0 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
10cc0 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
10cd0 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
10ce0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
10cf0 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70  ator.  For examp
10d00 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20  le,.** it might 
10d10 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71  allocate any req
10d20 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20  uire mutexes or 
10d30 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72  initialize inter
10d40 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75  nal data.** stru
10d50 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68  ctures.  The xSh
10d60 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
10d70 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65   invoked (indire
10d80 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c  ctly) by.** [sql
10d90 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
10da0 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c   and should deal
10db0 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75  locate any resou
10dc0 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a  rces acquired.**
10dd0 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20   by xInit.  The 
10de0 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72  pAppData pointer
10df0 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
10e00 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
10e10 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78  o.** xInit and x
10e20 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20  Shutdown..**.** 
10e30 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65  SQLite holds the
10e40 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
10e50 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75  TATIC_MASTER] mu
10e60 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f  tex when it invo
10e70 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74  kes.** the xInit
10e80 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20   method, so the 
10e90 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65  xInit method nee
10ea0 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73  d not be threads
10eb0 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68  afe.  The.** xSh
10ec0 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
10ed0 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f   only called fro
10ee0 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  m [sqlite3_shutd
10ef0 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65  own()] so it doe
10f00 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f  s.** not need to
10f10 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65   be threadsafe e
10f20 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20  ither.  For all 
10f30 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53  other methods, S
10f40 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74  QLite.** holds t
10f50 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
10f60 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74  _STATIC_MEM] mut
10f70 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ex as long as th
10f80 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
10f90 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63  FIG_MEMSTATUS] c
10fa0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10fb0 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e  ion is turned on
10fc0 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73   (which.** it is
10fd0 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64   by default) and
10fe0 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20   so the methods 
10ff0 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
11000 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a  y serialized..**
11010 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51   However, if [SQ
11020 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
11030 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c  TATUS] is disabl
11040 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68  ed, then the oth
11050 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75  er.** methods mu
11060 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
11070 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68   or else make th
11080 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d  eir own arrangem
11090 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69  ents for.** seri
110a0 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  alization..**.**
110b0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76   SQLite will nev
110c0 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28  er invoke xInit(
110d0 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  ) more than once
110e0 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65   without an inte
110f0 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20  rvening.** call 
11100 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a  to xShutdown()..
11110 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
11120 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
11130 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65  thods sqlite3_me
11140 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  m_methods;.struc
11150 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
11160 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a  thods {.  void *
11170 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b  (*xMalloc)(int);
11180 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f           /* Memo
11190 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75  ry allocation fu
111a0 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
111b0 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29   (*xFree)(void*)
111c0 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72  ;          /* Fr
111d0 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63  ee a prior alloc
111e0 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ation */.  void 
111f0 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69  *(*xRealloc)(voi
11200 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73  d*,int);  /* Res
11210 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f  ize an allocatio
11220 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69  n */.  int (*xSi
11230 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ze)(void*);     
11240 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20        /* Return 
11250 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61  the size of an a
11260 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
11270 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69  nt (*xRoundup)(i
11280 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  nt);          /*
11290 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73   Round up reques
112a0 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61  t size to alloca
112b0 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69  tion size */.  i
112c0 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64  nt (*xInit)(void
112d0 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
112e0 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   Initialize the 
112f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
11300 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68   */.  void (*xSh
11310 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20  utdown)(void*); 
11320 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61       /* Deinitia
11330 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
11340 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
11350 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
11360 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
11370 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e   Argument to xIn
11380 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f  it() and xShutdo
11390 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  wn() */.};../*.*
113a0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
113b0 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
113c0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
113d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
113e0 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion}.**.** Thes
113f0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
11400 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
11410 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
11420 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
11430 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
11440 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
11450 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
11460 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11470 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
11480 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
11490 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
114a0 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
114b0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
114c0 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
114d0 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
114e0 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
114f0 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
11500 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
11510 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
11520 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
11530 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  rom [sqlite3_con
11540 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
11550 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
11560 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68  call worked.  Th
11570 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
11580 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
11590 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
115a0 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
115b0 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
115c0 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
115d0 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
115e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
115f0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
11600 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
11610 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
11620 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  HREAD]] <dt>SQLI
11630 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
11640 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
11650 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
11660 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
11670 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
11680 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
11690 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
116a0 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74  ode] to Single-t
116b0 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
116c0 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
116d0 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
116e0 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c  ing and puts SQL
116f0 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20  ite into a mode 
11700 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c  where it can onl
11710 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20  y be used.** by 
11720 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  a single thread.
11730 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
11740 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
11750 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
11760 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
11770 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
11780 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
11790 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
117a0 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
117b0 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68  o change the [th
117c0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72  reading mode] fr
117d0 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a  om its default.*
117e0 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c  * value of Singl
117f0 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20  e-thread and so 
11800 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11810 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a  )] will return .
11820 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
11830 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
11840 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
11850 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a  IG_SINGLETHREAD.
11860 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
11870 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
11880 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
11890 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
118a0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
118b0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
118c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
118d0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
118e0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
118f0 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
11900 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
11910 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
11920 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20   Multi-thread.  
11930 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
11940 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d  it disables.** m
11950 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61  utexing on [data
11960 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11970 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
11980 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
11990 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  s..** The applic
119a0 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73  ation is respons
119b0 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69  ible for seriali
119c0 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a  zing access to.*
119d0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
119e0 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
119f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
11a00 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d  s].  But other m
11a10 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
11a20 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51  abled so that SQ
11a30 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66  Lite will be saf
11a40 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75  e to use in a mu
11a50 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  lti-threaded.** 
11a60 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c  environment as l
11a70 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68  ong as no two th
11a80 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f  reads attempt to
11a90 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a   use the same.**
11aa0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11ab0 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61  ction] at the sa
11ac0 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51  me time.  ^If SQ
11ad0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
11ae0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
11af0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
11b00 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
11b10 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
11b20 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
11b30 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
11b40 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
11b50 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   Multi-thread [t
11b60 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
11b70 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
11b80 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
11b90 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
11ba0 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
11bb0 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
11bc0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
11bd0 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  EAD configuratio
11be0 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
11bf0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11c00 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d  NFIG_SERIALIZED]
11c10 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11c20 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f  FIG_SERIALIZED</
11c30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
11c40 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
11c50 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
11c60 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
11c70 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
11c80 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
11c90 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f  Serialized. In o
11ca0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73  ther words, this
11cb0 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a   option enables.
11cc0 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69  ** all mutexes i
11cd0 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63  ncluding the rec
11ce0 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65  ursive.** mutexe
11cf0 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
11d00 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
11d10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
11d20 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
11d30 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68  In this mode (wh
11d40 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75  ich is the defau
11d50 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  lt when SQLite i
11d60 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
11d70 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  ** [SQLITE_THREA
11d80 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51  DSAFE=1]) the SQ
11d90 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
11da0 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69  l itself seriali
11db0 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ze access.** to 
11dc0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11dd0 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
11de0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
11df0 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20   so that the.** 
11e00 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66  application is f
11e10 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73  ree to use the s
11e20 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
11e30 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65  nnection] or the
11e40 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72  .** same [prepar
11e50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
11e60 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
11e70 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ds at the same t
11e80 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69  ime..** ^If SQLi
11e90 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
11ea0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
11eb0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
11ec0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11ed0 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
11ee0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
11ef0 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
11f00 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53  ble to set the S
11f10 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
11f20 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
11f30 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
11f40 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
11f50 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
11f60 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
11f70 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
11f80 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63  FIG_SERIALIZED c
11f90 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11fa0 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
11fb0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11fc0 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c  MALLOC]] <dt>SQL
11fd0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
11fe0 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
11ff0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
12000 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e  IG_MALLOC option
12010 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
12020 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
12030 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  s .** a pointer 
12040 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
12050 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
12060 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
12070 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72  cture..** The ar
12080 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
12090 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
120a0 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
120b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
120c0 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
120d0 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
120e0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
120f0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
12100 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
12110 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  )^ ^SQLite makes
12120 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76  .** its own priv
12130 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
12140 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
12150 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12160 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a  ods] structure.*
12170 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71  * before the [sq
12180 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12190 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64  call returns.</d
121a0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
121b0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
121c0 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
121d0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
121e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
121f0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
12200 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69  G_GETMALLOC opti
12210 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12220 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
12230 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
12240 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
12250 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
12260 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
12270 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b  ucture..** The [
12280 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12290 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
122a0 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
122b0 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
122c0 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c  efined memory al
122d0 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
122e0 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
122f0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
12300 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
12310 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
12320 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
12330 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
12340 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61  pper that simula
12350 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  tions memory all
12360 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20  ocation failure 
12370 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d  or.** tracks mem
12380 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65  ory usage, for e
12390 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  xample. </dd>.**
123a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
123b0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20  FIG_MEMSTATUS]] 
123c0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
123d0 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e  G_MEMSTATUS</dt>
123e0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
123f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
12400 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b  TATUS option tak
12410 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65  es single argume
12420 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a  nt of type int,.
12430 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ** interpreted a
12440 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69  s a boolean, whi
12450 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ch enables or di
12460 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65  sables the colle
12470 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f  ction of.** memo
12480 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
12490 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e  atistics. ^(When
124a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
124b0 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
124c0 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20  e disabled, the 
124d0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  .** following SQ
124e0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
124f0 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61  become non-opera
12500 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c  tional:.**   <ul
12510 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  >.**   <li> [sql
12520 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
12530 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
12540 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
12550 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20  ghwater()].**   
12560 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f  <li> [sqlite3_so
12570 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
12580 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
12590 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a  lite3_status()].
125a0 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  **   </ul>)^.** 
125b0 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69  ^Memory allocati
125c0 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
125d0 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66  e enabled by def
125e0 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69  ault unless SQLi
125f0 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
12600 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
12610 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53  EFAULT_MEMSTATUS
12620 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73  ]=0 in which cas
12630 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
12640 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
12650 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
12660 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f  y default..** </
12670 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
12680 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
12690 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  H]] <dt>SQLITE_C
126a0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
126b0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
126c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
126d0 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 73 70 65  RATCH option spe
126e0 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
126f0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a  memory buffer.**
12700 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
12710 20 75 73 65 20 66 6f 72 20 73 63 72 61 74 63 68   use for scratch
12720 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 68 65 72   memory.  ^(Ther
12730 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
12740 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 4c 49  ments.** to SQLI
12750 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
12760 48 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e  H:  A pointer an
12770 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e   8-byte.** align
12780 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ed memory buffer
12790 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
127a0 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
127b0 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64  ons will be.** d
127c0 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f  rawn, the size o
127d0 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61  f each scratch a
127e0 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a  llocation (sz),.
127f0 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ** and the maxim
12800 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72  um number of scr
12810 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
12820 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 66   (N).)^.** The f
12830 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
12840 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  st be a pointer 
12850 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69  to an 8-byte ali
12860 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f  gned buffer.** o
12870 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
12880 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
12890 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
128a0 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65 20 74 68   not use more th
128b0 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62  an one scratch b
128c0 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61  uffers per threa
128d0 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  d..** ^SQLite wi
128e0 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 65 73 74  ll never request
128f0 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65   a scratch buffe
12900 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74  r that is more t
12910 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74  han 6.** times t
12920 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
12930 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   size..** ^If SQ
12940 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73  Lite needs needs
12950 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73   additional.** s
12960 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65  cratch memory be
12970 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
12980 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f  vided by this co
12990 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
129a0 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71  on, then .** [sq
129b0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
129c0 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20  will be used to 
129d0 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72  obtain the memor
129e0 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20  y needed.<p>.** 
129f0 5e 57 68 65 6e 20 74 68 65 20 61 70 70 6c 69 63  ^When the applic
12a00 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 73 20 61  ation provides a
12a10 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63 72  ny amount of scr
12a20 61 74 63 68 20 6d 65 6d 6f 72 79 20 75 73 69 6e  atch memory usin
12a30 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  g.** SQLITE_CONF
12a40 49 47 5f 53 43 52 41 54 43 48 2c 20 53 51 4c 69  IG_SCRATCH, SQLi
12a50 74 65 20 61 76 6f 69 64 73 20 75 6e 6e 65 63 65  te avoids unnece
12a60 73 73 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20 5b  ssary large.** [
12a70 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68  sqlite3_malloc|h
12a80 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d  eap allocations]
12a90 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20 68 65  ..** This can he
12aa0 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66  lp [Robson proof
12ab0 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79 20  |prevent memory 
12ac0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
12ad0 72 65 73 5d 20 64 75 65 20 74 6f 20 68 65 61 70  res] due to heap
12ae0 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  .** fragmentatio
12af0 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20  n in low-memory 
12b00 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
12b10 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
12b20 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12b30 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74  _PAGECACHE]] <dt
12b40 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
12b50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  AGECACHE</dt>.**
12b60 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
12b70 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
12b80 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  HE option specif
12b90 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
12ba0 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  ory buffer.** th
12bb0 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
12bc0 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  e for the databa
12bd0 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69  se page cache wi
12be0 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70  th the default p
12bf0 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
12c00 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a  lementation.  .*
12c10 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61  * This configura
12c20 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20  tion should not 
12c30 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 70  be used if an ap
12c40 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
12c50 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
12c60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
12c70 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68   loaded using th
12c80 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
12c90 5f 50 43 41 43 48 45 32 5d 0a 2a 2a 20 63 6f 6e  _PCACHE2].** con
12ca0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12cb0 6e 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65  n..** ^There are
12cc0 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
12cd0 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
12ce0 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41 20 70  G_PAGECACHE: A p
12cf0 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65  ointer to 8-byte
12d00 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f   aligned.** memo
12d10 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ry, the size of 
12d20 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72  each page buffer
12d30 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e   (sz), and the n
12d40 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28  umber of pages (
12d50 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72  N)..** The sz ar
12d60 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
12d70 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
12d80 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73   largest databas
12d90 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77  e page.** (a pow
12da0 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65  er of two betwee
12db0 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 29  n 512 and 32768)
12dc0 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74 72 61   plus some extra
12dd0 20 62 79 74 65 73 20 66 6f 72 20 65 61 63 68 0a   bytes for each.
12de0 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20  ** page header. 
12df0 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
12e00 65 78 74 72 61 20 62 79 74 65 73 20 6e 65 65 64  extra bytes need
12e10 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 68  ed by the page h
12e20 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20  eader.** can be 
12e30 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
12e40 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
12e50 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
12e60 5d 20 6f 70 74 69 6f 6e 20 0a 2a 2a 20 74 6f 20  ] option .** to 
12e70 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12e80 29 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61  )]..** ^It is ha
12e90 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72  rmless, apart fr
12ea0 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65  om the wasted me
12eb0 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65  mory,.** for the
12ec0 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74 6f   sz parameter to
12ed0 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
12ee0 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 65 20  necessary.  The 
12ef0 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
12f00 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 65 72  t should pointer
12f10 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c   to an 8-byte al
12f20 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d  igned block of m
12f30 65 6d 6f 72 79 20 74 68 61 74 0a 2a 2a 20 69 73  emory that.** is
12f40 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
12f50 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  ytes of memory, 
12f60 6f 74 68 65 72 77 69 73 65 20 73 75 62 73 65 71  otherwise subseq
12f70 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73  uent behavior is
12f80 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
12f90 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
12fa0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
12fb0 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69  ovided by the fi
12fc0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
12fd0 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d  satisfy its.** m
12fe0 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20  emory needs for 
12ff0 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65  the first N page
13000 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74  s that it adds t
13010 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64  o cache.  ^If ad
13020 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
13030 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
13040 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
13050 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
13060 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20  by this option, 
13070 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67  then.** SQLite g
13080 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
13090 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68  malloc()] for th
130a0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f  e additional sto
130b0 72 61 67 65 20 73 70 61 63 65 2e 3c 2f 64 64 3e  rage space.</dd>
130c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
130d0 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64  CONFIG_HEAP]] <d
130e0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
130f0 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  HEAP</dt>.** <dd
13100 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
13110 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e  NFIG_HEAP option
13120 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
13130 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
13140 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74  r .** that SQLit
13150 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72 20 61  e will use for a
13160 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
13170 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  c memory allocat
13180 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79  ion needs.** bey
13190 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64  ond those provid
131a0 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54  ed for by [SQLIT
131b0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
131c0 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f  ] and [SQLITE_CO
131d0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
131e0 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74  .** ^There are t
131f0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
13200 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
13210 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79  HEAP:.** An 8-by
13220 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74  te aligned point
13230 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  er to the memory
13240 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  ,.** the number 
13250 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
13260 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61  memory buffer, a
13270 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  nd the minimum a
13280 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a  llocation size..
13290 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74  ** ^If the first
132a0 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
132b0 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73  mory pointer) is
132c0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69   NULL, then SQLi
132d0 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f  te reverts.** to
132e0 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75   using its defau
132f0 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
13300 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20  tor (the system 
13310 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65  malloc() impleme
13320 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64  ntation),.** und
13330 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69  oing any prior i
13340 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51  nvocation of [SQ
13350 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
13360 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  OC].  ^If the.**
13370 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20   memory pointer 
13380 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20  is not NULL and 
13390 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45  either [SQLITE_E
133a0 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f  NABLE_MEMSYS3] o
133b0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  r.** [SQLITE_ENA
133c0 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65  BLE_MEMSYS5] are
133d0 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74   defined, then t
133e0 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d  he alternative m
133f0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
13400 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f  or is engaged to
13410 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53   handle all of S
13420 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c  QLites memory al
13430 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a  location needs..
13440 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69  ** The first poi
13450 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
13460 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62   pointer) must b
13470 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
13480 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61  8-byte.** bounda
13490 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
134a0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
134b0 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  ite will be unde
134c0 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69  fined..** The mi
134d0 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
134e0 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20   size is capped 
134f0 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e  at 2**12. Reason
13500 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66  able values.** f
13510 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  or the minimum a
13520 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61  llocation size a
13530 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20  re 2**5 through 
13540 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  2**8.</dd>.**.**
13550 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13560 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  _MUTEX]] <dt>SQL
13570 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
13580 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
13590 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
135a0 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74  G_MUTEX option t
135b0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
135c0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
135d0 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
135e0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
135f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
13600 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
13610 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ture..** The arg
13620 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20  ument specifies 
13630 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
13640 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74  level mutex rout
13650 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
13660 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20  in place.** the 
13670 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62  mutex routines b
13680 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
13690 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
136a0 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
136b0 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  .** content of t
136c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
136d0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
136e0 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20  ture before the 
136f0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
13700 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65  te3_config()] re
13710 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74  turns. ^If SQLit
13720 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
13730 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
13740 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
13750 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
13760 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
13770 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
13780 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
13790 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
137a0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
137b0 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
137c0 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
137d0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
137e0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
137f0 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f  _CONFIG_MUTEX co
13800 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13810 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
13820 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
13830 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
13840 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
13850 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
13860 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
13870 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
13880 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
13890 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74  FIG_GETMUTEX opt
138a0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
138b0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
138c0 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
138d0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
138e0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
138f0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
13900 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
13910 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
13920 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
13930 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
13940 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
13950 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
13960 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  ex routines.)^.*
13970 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
13980 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
13990 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
139a0 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69  t mutex allocati
139b0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
139c0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73  ith a wrapper us
139d0 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65  ed to track mute
139e0 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66  x usage for perf
139f0 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69  ormance.** profi
13a00 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c  ling or testing,
13a10 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20   for example.   
13a20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
13a30 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
13a40 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
13a50 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
13a60 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
13a70 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
13a80 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
13a90 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
13aa0 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
13ab0 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
13ac0 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
13ad0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
13ae0 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
13af0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13b00 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67  _GETMUTEX config
13b10 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
13b20 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
13b30 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
13b40 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13b50 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
13b60 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  DE]] <dt>SQLITE_
13b70 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
13b80 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
13b90 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
13ba0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69  G_LOOKASIDE opti
13bb0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
13bc0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
13bd0 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66  rmine.** the def
13be0 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f  ault size of loo
13bf0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e  kaside memory on
13c00 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20   each [database 
13c10 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
13c20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
13c30 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
13c40 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
13c50 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20  ide buffer slot 
13c60 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69  and the second i
13c70 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
13c80 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74  ** slots allocat
13c90 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ed to each datab
13ca0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29  ase connection.)
13cb0 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46  ^  ^(SQLITE_CONF
13cc0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20  IG_LOOKASIDE.** 
13cd0 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61  sets the <i>defa
13ce0 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
13cf0 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
13d00 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
13d10 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f  KASIDE].** optio
13d20 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  n to [sqlite3_db
13d30 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62  _config()] can b
13d40 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65  e used to change
13d50 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a   the lookaside.*
13d60 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
13d70 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f  on individual co
13d80 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64  nnections.)^ </d
13d90 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13da0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
13db0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13dc0 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74  NFIG_PCACHE2</dt
13dd0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
13de0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
13df0 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
13e00 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13e10 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a  ment which is .*
13e20 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
13e30 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
13e40 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
13e50 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ct.  This object
13e60 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
13e70 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61  e interface to a
13e80 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63   custom page cac
13e90 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
13ea0 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  n.)^.** ^SQLite 
13eb0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
13ec0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  the [sqlite3_pca
13ed0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
13ee0 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ject.</dd>.**.**
13ef0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13f00 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64  _GETPCACHE2]] <d
13f10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13f20 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  GETPCACHE2</dt>.
13f30 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
13f40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
13f50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61  CACHE2 option ta
13f60 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
13f70 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
13f80 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
13f90 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
13fa0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
13fb0 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
13fc0 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  es of the curren
13fd0 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  t.** page cache 
13fe0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
13ff0 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
14000 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
14010 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
14020 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OG]] <dt>SQLITE_
14030 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a  CONFIG_LOG</dt>.
14040 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49  ** <dd> The SQLI
14050 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
14060 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
14070 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51  configure the SQ
14080 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b  Lite.** global [
14090 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28  error log]..** (
140a0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
140b0 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61  IG_LOG option ta
140c0 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
140d0 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: a pointer to 
140e0 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  a.** function wi
140f0 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74  th a call signat
14100 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76  ure of void(*)(v
14110 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
14120 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61  har*), .** and a
14130 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64   pointer to void
14140 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  . ^If the functi
14150 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
14160 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a  t NULL, it is.**
14170 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c   invoked by [sql
14180 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70  ite3_log()] to p
14190 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67  rocess each logg
141a0 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
141b0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
141c0 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c  pointer is NULL,
141d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
141e0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  g()] interface b
141f0 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a  ecomes a no-op..
14200 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69  ** ^The void poi
14210 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65  nter that is the
14220 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
14230 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
14240 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73  G_LOG is.** pass
14250 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
14260 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
14270 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  r to the applica
14280 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
14290 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
142a0 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75  whenever that fu
142b0 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
142c0 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  d.  ^The second 
142d0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
142e0 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
142f0 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ion is a copy of
14300 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
14310 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72  eter to the corr
14320 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71  esponding.** [sq
14330 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c  lite3_log()] cal
14340 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65  l and is intende
14350 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c  d to be a [resul
14360 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  t code] or an.**
14370 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
14380 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74  t code].  ^The t
14390 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70  hird parameter p
143a0 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67  assed to the log
143b0 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65  ger is.** log me
143c0 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d  ssage after form
143d0 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69  atting via [sqli
143e0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e  te3_snprintf()].
143f0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c  .** The SQLite l
14400 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65  ogging interface
14410 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
14420 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  t; the logger fu
14430 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  nction.** suppli
14440 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
14450 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69  ation must not i
14460 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65  nvoke any SQLite
14470 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
14480 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
14490 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  ed application, 
144a0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
144b0 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
144c0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
144d0 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c  be threadsafe. <
144e0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
144f0 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d  ITE_CONFIG_URI]]
14500 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14510 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28  IG_URI.** <dd>^(
14520 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14530 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b  G_URI option tak
14540 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
14550 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
14560 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f  ..** If non-zero
14570 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c  , then URI handl
14580 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
14590 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20  enabled. If the 
145a0 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72  parameter is zer
145b0 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68  o,.** then URI h
145c0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
145d0 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20  lly disabled.)^ 
145e0 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  ^If URI handling
145f0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61   is globally ena
14600 62 6c 65 64 2c 0a 2a 2a 20 61 6c 6c 20 66 69 6c  bled,.** all fil
14610 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f  enames passed to
14620 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
14630 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
14640 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
14650 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a  _open16()] or.**
14660 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61   specified as pa
14670 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63  rt of [ATTACH] c
14680 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65  ommands are inte
14690 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c  rpreted as URIs,
146a0 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f   regardless.** o
146b0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
146c0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
146d0 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73  N_URI] flag is s
146e0 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  et when the data
146f0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
14700 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49  on is opened. ^I
14710 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79  f it is globally
14720 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e   disabled, filen
14730 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79  ames are.** only
14740 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
14750 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49  URIs if the SQLI
14760 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67  TE_OPEN_URI flag
14770 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
14780 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
14790 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
147a0 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c  d. ^(By default,
147b0 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
147c0 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73   globally.** dis
147d0 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75  abled. The defau
147e0 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20  lt value may be 
147f0 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69  changed by compi
14800 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a  ling with the.**
14810 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
14820 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  ] symbol defined
14830 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
14840 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
14850 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20  NG_INDEX_SCAN]] 
14860 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14870 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
14880 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68  _SCAN.** <dd>^Th
14890 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
148a0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
148b0 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  CAN option takes
148c0 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65   a single intege
148d0 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68  r.** argument wh
148e0 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ich is interpret
148f0 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20  ed as a boolean 
14900 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62  in order to enab
14910 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a  le or disable.**
14920 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65   the use of cove
14930 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72  ring indices for
14940 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e   full table scan
14950 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f  s in the query o
14960 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68  ptimizer..** ^Th
14970 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
14980 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a  g is determined.
14990 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  ** by the [SQLIT
149a0 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47  E_ALLOW_COVERING
149b0 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d  _INDEX_SCAN] com
149c0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
149d0 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20  , or is "on".** 
149e0 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d  if that compile-
149f0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f  time option is o
14a00 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61  mitted..** The a
14a10 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c  bility to disabl
14a20 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  e the use of cov
14a30 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
14a40 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  r full table sca
14a50 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65  ns.** is because
14a60 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c   some incorrectl
14a70 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61  y coded legacy a
14a80 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68  pplications migh
14a90 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a  t malfunction.**
14aa0 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69   when the optimi
14ab0 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  zation is enable
14ac0 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68  d.  Providing th
14ad0 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20  e ability to.** 
14ae0 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69  disable the opti
14af0 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  mization allows 
14b00 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79  the older, buggy
14b10 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
14b20 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74  e to work.** wit
14b30 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e  hout change even
14b40 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72 73   with newer vers
14b50 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
14b60 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14b70 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b  ONFIG_PCACHE]] [
14b80 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
14b90 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64  ETPCACHE]].** <d
14ba0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14bb0 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54  PCACHE and SQLIT
14bc0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
14bd0 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65  HE.** <dd> These
14be0 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73   options are obs
14bf0 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64  olete and should
14c00 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20   not be used by 
14c10 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65  new code..** The
14c20 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66  y are retained f
14c30 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
14c40 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 61  patibility but a
14c50 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a  re now no-ops..*
14c60 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
14c70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
14c80 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  LLOG]].** <dt>SQ
14c90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
14ca0 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  OG.** <dd>This o
14cb0 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
14cc0 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74  ailable if sqlit
14cd0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
14ce0 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
14cf0 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d  E_ENABLE_SQLLOG]
14d00 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d   pre-processor m
14d10 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68  acro defined. Th
14d20 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
14d30 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20   should.** be a 
14d40 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e  pointer to a fun
14d50 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f  ction of type vo
14d60 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
14d70 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  te3*,const char*
14d80 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73  , int)..** The s
14d90 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20  econd should be 
14da0 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e  of type (void*).
14db0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   The callback is
14dc0 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20   invoked by the 
14dd0 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68  library.** in th
14de0 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69 72  ree separate cir
14df0 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e  cumstances, iden
14e00 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76 61  tified by the va
14e10 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
14e20 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61  e.** fourth para
14e30 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f  meter. If the fo
14e40 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
14e50 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61  s 0, then the da
14e60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14e70 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74  n.** passed as t
14e80 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
14e90 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  nt has just been
14ea0 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69   opened. The thi
14eb0 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70  rd argument.** p
14ec0 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65  oints to a buffe
14ed0 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  r containing the
14ee0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69   name of the mai
14ef0 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  n database file.
14f00 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   If the.** fourt
14f10 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 31  h parameter is 1
14f20 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73  , then the SQL s
14f30 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68  tatement that th
14f40 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
14f50 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68  r.** points to h
14f60 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65  as just been exe
14f70 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68  cuted. Or, if th
14f80 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
14f90 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a  er is 2, then.**
14fa0 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   the connection 
14fb0 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 20  being passed as 
14fc0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
14fd0 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c  eter is being cl
14fe0 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69  osed. The.** thi
14ff0 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
15000 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74  passed NULL In t
15010 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78  his case.  An ex
15020 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74  ample of using t
15030 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  his.** configura
15040 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20  tion option can 
15050 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22  be seen in the "
15060 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73  test_sqllog.c" s
15070 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a  ource file in.**
15080 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53   the canonical S
15090 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72 65  QLite source tre
150a0 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  e.</dd>.**.** [[
150b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
150c0 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74  AP_SIZE]].** <dt
150d0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
150e0 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e  MAP_SIZE.** <dd>
150f0 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  ^SQLITE_CONFIG_M
15100 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74  MAP_SIZE takes t
15110 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  wo 64-bit intege
15120 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  r (sqlite3_int64
15130 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  ) values.** that
15140 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c 74   are the default
15150 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
15160 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73 65   (the default se
15170 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52  tting for.** [PR
15180 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29  AGMA mmap_size])
15190 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d   and the maximum
151a0 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
151b0 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68  ze limit..** ^Th
151c0 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
151d0 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  g can be overrid
151e0 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74 61  den by each data
151f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
15200 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20  using.** either 
15210 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  the [PRAGMA mmap
15220 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20  _size] command, 
15230 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a  or by using the.
15240 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
15250 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
15260 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65   control.  ^(The
15270 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
15280 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 63 61   mmap size.** ca
15290 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20  nnot be changed 
152a0 61 74 20 72 75 6e 2d 74 69 6d 65 2e 20 20 4e 6f  at run-time.  No
152b0 72 20 6d 61 79 20 74 68 65 20 6d 61 78 69 6d 75  r may the maximu
152c0 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73  m allowed mmap s
152d0 69 7a 65 0a 2a 2a 20 65 78 63 65 65 64 20 74 68  ize.** exceed th
152e0 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d  e compile-time m
152f0 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65  aximum mmap size
15300 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b   set by the.** [
15310 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f  SQLITE_MAX_MMAP_
15320 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SIZE] compile-ti
15330 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20  me option.)^.** 
15340 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 75 6d  ^If either argum
15350 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69  ent to this opti
15360 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  on is negative, 
15370 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65  then that argume
15380 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64  nt is.** changed
15390 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d   to its compile-
153a0 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  time default..**
153b0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
153c0 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
153d0 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  ZE]].** <dt>SQLI
153e0 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
153f0 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e  HEAPSIZE.** <dd>
15400 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
15410 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
15420 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  E option is only
15430 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51   available if SQ
15440 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  Lite is.** compi
15450 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20  led for Windows 
15460 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
15470 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70  _WIN32_MALLOC] p
15480 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
15490 72 6f 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e  ro defined..** ^
154a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
154b0 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b  N32_HEAPSIZE tak
154c0 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69  es a 32-bit unsi
154d0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c  gned integer val
154e0 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69  ue.** that speci
154f0 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  fies the maximum
15500 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65   size of the cre
15510 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f  ated heap..** </
15520 64 6c 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dl>.**.** [[SQLI
15530 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15540 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e  _HDRSZ]].** <dt>
15550 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15560 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64  ACHE_HDRSZ.** <d
15570 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
15580 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
15590 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  Z option takes a
155a0 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
155b0 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  r which.** is a 
155c0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
155d0 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73  teger and writes
155e0 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67   into that integ
155f0 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  er the number of
15600 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20   extra.** bytes 
15610 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65  per page require
15620 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20  d for each page 
15630 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  in [SQLITE_CONFI
15640 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 20 54 68  G_PAGECACHE]. Th
15650 65 20 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20 65  e amount of.** e
15660 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69  xtra space requi
15670 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64  red can change d
15680 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
15690 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72  compiler,.** tar
156a0 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e  get platform, an
156b0 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
156c0 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ..** </dl>.*/.#d
156d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
156e0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
156f0 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    1  /* nil */.#
15700 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15710 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
15720 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     2  /* nil */.
15730 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15740 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
15750 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f      3  /* nil */
15760 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15770 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20  CONFIG_MALLOC   
15780 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74       4  /* sqlit
15790 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
157a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
157b0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
157c0 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c  OC     5  /* sql
157d0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
157e0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
157f0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
15800 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76  CH       6  /* v
15810 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
15820 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
15830 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
15840 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a  ECACHE     7  /*
15850 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
15860 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
15870 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
15880 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20  EAP          8  
15890 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42  /* void*, int nB
158a0 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a  yte, int min */.
158b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
158c0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
158d0 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61      9  /* boolea
158e0 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
158f0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
15900 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73          10  /* s
15910 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
15920 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
15930 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
15940 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20  ETMUTEX     11  
15950 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
15960 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20  _methods* */./* 
15970 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54  previously SQLIT
15980 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c  E_CONFIG_CHUNKAL
15990 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20  LOC 12 which is 
159a0 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a  now unused. */ .
159b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
159c0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
159d0 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e     13  /* int in
159e0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
159f0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
15a00 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e  E       14  /* n
15a10 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20  o-op */.#define 
15a20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
15a30 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f  TPCACHE    15  /
15a40 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
15a50 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15a60 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36  _LOG          16
15a70 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64    /* xFunc, void
15a80 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
15a90 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20  ITE_CONFIG_URI  
15aa0 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69          17  /* i
15ab0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
15ac0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15ad0 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20  HE2      18  /* 
15ae0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
15af0 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66  ethods2* */.#def
15b00 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15b10 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 31  G_GETPCACHE2   1
15b20 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  9  /* sqlite3_pc
15b30 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a  ache_methods2* *
15b40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15b50 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
15b60 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20  _INDEX_SCAN 20  
15b70 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
15b80 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15b90 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20  SQLLOG       21 
15ba0 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69   /* xSqllog, voi
15bb0 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d* */.#define SQ
15bc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
15bd0 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20  _SIZE    22  /* 
15be0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73  sqlite3_int64, s
15bf0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a  qlite3_int64 */.
15c00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15c10 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
15c20 53 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a  SIZE      23  /*
15c30 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64   int nByte */.#d
15c40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15c50 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
15c60 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69          24  /* i
15c70 6e 74 20 2a 70 73 7a 20 2a 2f 0a 0a 2f 2a 0a 2a  nt *psz */../*.*
15c80 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
15c90 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
15ca0 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
15cb0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
15cc0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
15cd0 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
15ce0 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
15cf0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
15d00 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
15d10 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
15d20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
15d30 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
15d40 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
15d50 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
15d60 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
15d70 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
15d80 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
15d90 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
15da0 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
15db0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
15dc0 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
15dd0 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
15de0 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
15df0 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
15e00 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
15e10 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
15e20 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
15e30 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
15e40 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  ed.  ^The [sqlit
15e50 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
15e60 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
15e70 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
15e80 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
15e90 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
15ea0 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
15eb0 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
15ec0 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
15ed0 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
15ee0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
15ef0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
15f00 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
15f10 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
15f20 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
15f30 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
15f40 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
15f50 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
15f60 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
15f70 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
15f80 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
15f90 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
15fa0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
15fb0 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
15fc0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
15fd0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
15fe0 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
15ff0 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62  er to a memory b
16000 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
16010 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
16020 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  y..** ^The first
16030 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20   argument after 
16040 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
16050 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65  FIG_LOOKASIDE ve
16060 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rb.** may be NUL
16070 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
16080 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
16090 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b  cate the.** look
160a0 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73  aside buffer its
160b0 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
160c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54  e3_malloc()]. ^T
160d0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
160e0 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
160f0 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
16100 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e  ide buffer slot.
16110 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67    ^The third arg
16120 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
16130 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
16140 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
16150 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
16160 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
16170 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
16180 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
16190 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
161a0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
161b0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
161c0 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a  .  The buffer.**
161d0 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
161e0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
161f0 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65  undary.  ^If the
16200 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
16210 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42   to.** SQLITE_DB
16220 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
16230 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70   is not a multip
16240 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69  le of 8, it is i
16250 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75  nternally.** rou
16260 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65  nded down to the
16270 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75   next smaller mu
16280 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28  ltiple of 8.  ^(
16290 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  The lookaside me
162a0 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  mory.** configur
162b0 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61  ation for a data
162c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
162d0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e  can only be chan
162e0 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a  ged when that.**
162f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e   connection is n
16300 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69  ot currently usi
16310 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  ng lookaside mem
16320 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72  ory, or in other
16330 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74   words.** when t
16340 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75  he "current valu
16350 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  e" returned by.*
16360 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74  * [sqlite3_db_st
16370 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  atus](D,[SQLITE_
16380 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
16390 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a  ],...) is zero..
163a0 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
163b0 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
163c0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f  kaside memory co
163d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e  nfiguration when
163e0 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65   lookaside.** me
163f0 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c  mory is in use l
16400 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67  eaves the config
16410 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65  uration unchange
16420 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a  d and returns .*
16430 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
16440 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  )^</dd>.**.** <d
16450 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
16460 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64  G_ENABLE_FKEY</d
16470 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
16480 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
16490 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
164a0 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65  able the enforce
164b0 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65  ment of.** [fore
164c0 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
164d0 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f  nts].  There sho
164e0 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
164f0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
16500 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
16510 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
16520 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
16530 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e  to disable FK en
16540 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f  forcement,.** po
16550 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
16560 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
16570 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
16580 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  eave FK enforcem
16590 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ent.** unchanged
165a0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
165b0 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
165c0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
165d0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
165e0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
165f0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
16600 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63  hether FK enforc
16610 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20  ement is off or 
16620 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  on.** following 
16630 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
16640 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16650 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
16660 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
16670 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20  ich case the FK 
16680 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74  enforcement sett
16690 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
166a0 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
166b0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
166c0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
166d0 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a  _TRIGGER</dt>.**
166e0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
166f0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
16700 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
16710 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
16720 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20  | triggers]..** 
16730 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
16740 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
16750 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
16760 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
16770 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
16780 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
16790 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a  ble triggers,.**
167a0 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
167b0 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20  ble triggers or 
167c0 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
167d0 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e  e the setting un
167e0 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
167f0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16800 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
16810 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
16820 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
16830 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
16840 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
16850 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73  triggers are dis
16860 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
16870 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
16880 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
16890 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
168a0 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
168b0 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
168c0 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67  h case the trigg
168d0 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  er setting is no
168e0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
168f0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64   </dd>.**.** </d
16900 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
16910 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
16920 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30  OKASIDE       10
16930 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  01  /* void* int
16940 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
16950 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16960 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20  ENABLE_FKEY     
16970 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74  1002  /* int int
16980 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
16990 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
169a0 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30  BLE_TRIGGER  100
169b0 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  3  /* int int* *
169c0 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  /.../*.** CAPI3R
169d0 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
169e0 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
169f0 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a  esult Codes.**.*
16a00 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
16a10 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
16a20 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
16a30 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
16a40 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
16a50 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
16a60 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
16a70 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64  ite. ^The extend
16a80 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
16a90 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
16aa0 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
16ab0 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
16ac0 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20  ibility..*/.int 
16ad0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
16ae0 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71  _result_codes(sq
16af0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66  lite3*, int onof
16b00 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
16b10 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74  REF: Last Insert
16b20 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61   Rowid.**.** ^Ea
16b30 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74  ch entry in most
16b40 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28   SQLite tables (
16b50 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48  except for [WITH
16b60 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
16b70 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71  s).** has a uniq
16b80 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
16b90 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
16ba0 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
16bb0 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
16bc0 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
16bd0 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
16be0 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
16bf0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
16c00 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
16c10 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
16c20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
16c30 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
16c40 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
16c50 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
16c60 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
16c70 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
16c80 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
16c90 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
16ca0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
16cb0 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
16cc0 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
16cd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
16ce0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
16cf0 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61  rowid(D) interfa
16d00 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
16d10 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a  rowid] of the .*
16d20 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75  * most recent su
16d30 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
16d40 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74  ] into a rowid t
16d50 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c  able or [virtual
16d60 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61   table].** on da
16d70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16d80 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73  n D..** ^Inserts
16d90 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52   into [WITHOUT R
16da0 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65  OWID] tables are
16db0 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a   not recorded..*
16dc0 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73  * ^If no success
16dd0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e  ful [INSERT]s in
16de0 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a  to rowid tables.
16df0 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
16e00 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74  urred on the dat
16e10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16e20 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c   D, .** then sql
16e30 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
16e40 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e  _rowid(D) return
16e50 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28  s zero..**.** ^(
16e60 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
16e70 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
16e80 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e  rigger or within
16e90 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
16ea0 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68  e].** method, th
16eb0 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
16ec0 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  will return the 
16ed0 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
16ee0 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61  nserted.** row a
16ef0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
16f00 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
16f10 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73   table method is
16f20 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
16f30 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
16f40 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
16f50 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20  le method ends, 
16f60 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
16f70 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72  ed .** by this r
16f80 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74  outine reverts t
16f90 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65  o what it was be
16fa0 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
16fb0 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74   or virtual.** t
16fc0 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61  able method bega
16fd0 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b  n.)^.**.** ^An [
16fe0 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69  INSERT] that fai
16ff0 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
17000 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
17010 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
17020 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
17030 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
17040 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
17050 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
17060 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68  ** routine.  ^Th
17070 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
17080 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
17090 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
170a0 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
170b0 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
170c0 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
170d0 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
170e0 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
170f0 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
17100 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
17110 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52  s.  ^(When INSER
17120 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20  T OR REPLACE.** 
17130 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e  encounters a con
17140 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
17150 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66  n, it does not f
17160 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53  ail.  The.** INS
17170 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ERT continues to
17180 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65   completion afte
17190 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20  r deleting rows 
171a0 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74  that caused.** t
171b0 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72  he constraint pr
171c0 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20  oblem so INSERT 
171d0 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20  OR REPLACE will 
171e0 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a  always change.**
171f0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
17200 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
17210 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  ace.)^.**.** ^Fo
17220 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
17230 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
17240 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63  an [INSERT] is c
17250 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
17260 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
17270 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
17280 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
17290 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  back..**.** This
172a0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63   function is acc
172b0 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73  essible to SQL s
172c0 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68  tatements via th
172d0 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72  e.** [last_inser
172e0 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75  t_rowid() SQL fu
172f0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
17300 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
17310 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
17320 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74  ew [INSERT] on t
17330 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62  he same.** datab
17340 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
17350 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
17360 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
17370 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  wid()].** functi
17380 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
17390 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
173a0 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  he last insert [
173b0 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20  rowid],.** then 
173c0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
173d0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
173e0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
173f0 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64  ()] is.** unpred
17400 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
17410 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
17420 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
17430 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e  e new.** last in
17440 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f  sert [rowid]..*/
17450 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
17460 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
17470 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
17480 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
17490 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
174a0 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
174b0 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
174c0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
174d0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
174e0 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c  f rows modified,
174f0 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20   inserted or.** 
17500 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d  deleted by the m
17510 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
17520 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
17530 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 0a  PDATE or DELETE.
17540 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20  ** statement on 
17550 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
17560 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65  nection specifie
17570 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70 61  d by the only pa
17580 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65  rameter..** ^Exe
17590 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72  cuting any other
175a0 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61   type of SQL sta
175b0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
175c0 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75 65  modify the value
175d0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
175e0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  this function..*
175f0 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67  *.** ^Only chang
17600 65 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c 79  es made directly
17610 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20   by the INSERT, 
17620 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
17630 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a   statement are.*
17640 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20 61  * considered - a
17650 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73  uxiliary changes
17660 20 63 61 75 73 65 64 20 62 79 20 5b 43 52 45 41   caused by [CREA
17670 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
17680 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72  ggers], .** [for
17690 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
176a0 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20 63  ] or [REPLACE] c
176b0 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
176c0 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75  tion are not cou
176d0 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61  nted..** .** Cha
176e0 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
176f0 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70  hat are intercep
17700 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54  ted by .** [INST
17710 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 7c  EAD OF trigger |
17720 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67   INSTEAD OF trig
17730 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f  gers] are not co
17740 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c 75  unted. ^The valu
17750 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  e .** returned b
17760 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  y sqlite3_change
17770 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  s() immediately 
17780 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54 2c  after an INSERT,
17790 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44   UPDATE or .** D
177a0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
177b0 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69 73  run on a view is
177c0 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e   always zero. On
177d0 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  ly changes made 
177e0 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c  to real .** tabl
177f0 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a  es are counted..
17800 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72 65  **.** Things are
17810 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65   more complicate
17820 64 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33  d if the sqlite3
17830 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74  _changes() funct
17840 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75 74  ion is.** execut
17850 65 64 20 77 68 69 6c 65 20 61 20 74 72 69 67 67  ed while a trigg
17860 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72 75  er program is ru
17870 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79 20  nning. This may 
17880 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a  happen if the.**
17890 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74 68   program uses th
178a0 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
178b0 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69   function], or i
178c0 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c  f some other cal
178d0 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
178e0 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65  n invokes sqlite
178f0 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72 65  3_changes() dire
17900 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c  ctly. Essentiall
17910 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a  y:.** .** <ul>.*
17920 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72  *   <li> ^(Befor
17930 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72 69  e entering a tri
17940 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68 65  gger program the
17950 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
17960 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71 6c  by.**        sql
17970 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66  ite3_changes() f
17980 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65 64  unction is saved
17990 2e 20 41 66 74 65 72 20 74 68 65 20 74 72 69 67  . After the trig
179a0 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20  ger program .** 
179b0 20 20 20 20 20 20 20 68 61 73 20 66 69 6e 69 73         has finis
179c0 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e 61  hed, the origina
179d0 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73 74 6f  l value is resto
179e0 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20  red.)^.** .**   
179f0 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61 20  <li> ^(Within a 
17a00 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
17a10 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50 44  each INSERT, UPD
17a20 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20 0a  ATE and DELETE .
17a30 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74 65 6d  **        statem
17a40 65 6e 74 20 73 65 74 73 20 74 68 65 20 76 61 6c  ent sets the val
17a50 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
17a60 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
17a70 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f 6e   .**        upon
17a80 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e   completion as n
17a90 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65  ormal. Of course
17aa0 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77 69 6c  , this value wil
17ab0 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a  l not include .*
17ac0 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63 68 61  *        any cha
17ad0 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20 62  nges performed b
17ae0 79 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c 20  y sub-triggers, 
17af0 61 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  as the sqlite3_c
17b00 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20  hanges() .**    
17b10 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20 62      value will b
17b20 65 20 73 61 76 65 64 20 61 6e 64 20 72 65 73 74  e saved and rest
17b30 6f 72 65 64 20 61 66 74 65 72 20 65 61 63 68 20  ored after each 
17b40 73 75 62 2d 74 72 69 67 67 65 72 20 68 61 73 20  sub-trigger has 
17b50 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  run.)^.** </ul>.
17b60 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61  ** .** ^This mea
17b70 6e 73 20 74 68 61 74 20 69 66 20 74 68 65 20 63  ns that if the c
17b80 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
17b90 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61  ction (or simila
17ba0 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79  r) is used.** by
17bb0 20 74 68 65 20 66 69 72 73 74 20 49 4e 53 45 52   the first INSER
17bc0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
17bd0 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
17be0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20  thin a trigger, 
17bf0 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74  it .** returns t
17c00 68 65 20 76 61 6c 75 65 20 61 73 20 73 65 74 20  he value as set 
17c10 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67  when the calling
17c20 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61 6e   statement began
17c30 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
17c40 49 66 20 69 74 20 69 73 20 75 73 65 64 20 62 79  If it is used by
17c50 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73   the second or s
17c60 75 62 73 65 71 75 65 6e 74 20 73 75 63 68 20 73  ubsequent such s
17c70 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
17c80 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70 72  a trigger .** pr
17c90 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75 65  ogram, the value
17ca0 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65 63   returned reflec
17cb0 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ts the number of
17cc0 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20 62   rows modified b
17cd0 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f  y the .** previo
17ce0 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  us INSERT, UPDAT
17cf0 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
17d00 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
17d10 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a   same trigger..*
17d20 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
17d30 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
17d40 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
17d50 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
17d60 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
17d70 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63  gma], and the [c
17d80 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
17d90 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
17da0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
17db0 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
17dc0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
17dd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17de0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
17df0 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  e3_changes()] is
17e00 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
17e10 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
17e20 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74  .** is unpredict
17e30 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
17e40 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
17e50 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
17e60 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
17e70 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
17e80 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
17e90 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20   Modified.**.** 
17ea0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
17eb0 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c  eturns the total
17ec0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
17ed0 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69 66 69  inserted, modifi
17ee0 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64  ed or.** deleted
17ef0 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d   by all [INSERT]
17f00 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44  , [UPDATE] or [D
17f10 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
17f20 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73  s completed.** s
17f30 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73  ince the databas
17f40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73  e connection was
17f50 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69   opened, includi
17f60 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75 74 65  ng those execute
17f70 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20  d as.** part of 
17f80 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73  trigger programs
17f90 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79  . ^Executing any
17fa0 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53   other type of S
17fb0 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
17fc0 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63 74 20  does not affect 
17fd0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
17fe0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
17ff0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a  tal_changes()..*
18000 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d  * .** ^Changes m
18010 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 5b  ade as part of [
18020 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
18030 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75 64 65  ons] are include
18040 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e  d in the.** coun
18050 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d 61 64  t, but those mad
18060 65 20 61 73 20 70 61 72 74 20 6f 66 20 52 45 50  e as part of REP
18070 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20  LACE constraint 
18080 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a  resolution are.*
18090 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20  * not. ^Changes 
180a0 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
180b0 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62  re intercepted b
180c0 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  y INSTEAD OF tri
180d0 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f  ggers .** are no
180e0 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a  t counted..** .*
180f0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
18100 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
18110 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
18120 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
18130 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
18140 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e   the [total_chan
18150 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
18160 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
18170 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
18180 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
18190 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
181a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
181b0 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
181c0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
181d0 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
181e0 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
181f0 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64  turned is unpred
18200 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
18210 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
18220 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  nt sqlite3_total
18230 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
18240 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
18250 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41  REF: Interrupt A
18260 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75   Long-Running Qu
18270 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ery.**.** ^This 
18280 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
18290 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
182a0 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
182b0 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
182c0 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
182d0 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
182e0 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
182f0 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
18300 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
18310 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
18320 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
18330 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
18340 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
18350 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
18360 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
18370 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
18380 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
18390 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65  *.** ^It is safe
183a0 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
183b0 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
183c0 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
183d0 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
183e0 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
183f0 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
18400 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
18410 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
18420 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
18430 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
18440 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
18450 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
18460 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
18470 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
18480 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
18490 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
184a0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51  .**.** ^If an SQ
184b0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
184c0 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
184d0 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
184e0 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
184f0 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
18500 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
18510 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
18520 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
18530 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
18540 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
18550 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
18560 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51  on..**.** ^An SQ
18570 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
18580 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
18590 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
185a0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
185b0 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72  ** ^If the inter
185c0 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
185d0 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
185e0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
185f0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
18600 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
18610 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
18620 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
18630 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
18640 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
18650 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
18660 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
18670 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
18680 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
18690 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
186a0 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
186b0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
186c0 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
186d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
186e0 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77  plete.  ^Any new
186f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
18700 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
18710 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
18720 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
18730 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
18740 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
18750 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
18760 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
18770 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
18780 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
18790 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
187a0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
187b0 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
187c0 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d   ^New SQL statem
187d0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
187e0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
187f0 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  he running state
18800 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68  ment count reach
18810 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e  es zero are.** n
18820 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74  ot effected by t
18830 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
18840 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61  rupt()..** ^A ca
18850 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
18860 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
18870 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
18880 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
18890 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
188a0 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
188b0 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
188c0 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
188d0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
188e0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
188f0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
18900 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
18910 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64  ..**.** If the d
18920 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18930 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
18940 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
18950 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e  pt()].** is runn
18960 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69  ing then bad thi
18970 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ngs will likely 
18980 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20  happen..*/.void 
18990 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
189a0 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
189b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
189c0 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
189d0 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43  L Statement Is C
189e0 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68  omplete.**.** Th
189f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
18a00 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63   useful during c
18a10 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75  ommand-line inpu
18a20 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69  t to determine i
18a30 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  f the.** current
18a40 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20  ly entered text 
18a50 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20  seems to form a 
18a60 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
18a70 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20  tement or.** if 
18a80 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74  additional input
18a90 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72   is needed befor
18aa0 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65  e sending the te
18ab0 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74  xt into.** SQLit
18ac0 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20  e for parsing.  
18ad0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
18ae0 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20  return 1 if the 
18af0 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
18b00 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
18b10 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
18b20 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74  tement.  ^A stat
18b30 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20  ement is judged 
18b40 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  to be.** complet
18b50 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74  e if it ends wit
18b60 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f  h a semicolon to
18b70 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ken and is not a
18b80 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20   prefix of a.** 
18b90 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41  well-formed CREA
18ba0 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65  TE TRIGGER state
18bb0 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f  ment.  ^Semicolo
18bc0 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65  ns that are embe
18bd0 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73  dded within.** s
18be0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f  tring literals o
18bf0 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66  r quoted identif
18c00 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d  ier names or com
18c10 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ments are not.**
18c20 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b   independent tok
18c30 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61  ens (they are pa
18c40 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20  rt of the token 
18c50 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72  in which they ar
18c60 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61  e.** embedded) a
18c70 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63  nd thus do not c
18c80 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d  ount as a statem
18c90 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ent terminator. 
18ca0 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20   ^Whitespace.** 
18cb0 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61  and comments tha
18cc0 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e  t follow the fin
18cd0 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65  al semicolon are
18ce0 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
18cf0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
18d00 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20  return 0 if the 
18d10 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63  statement is inc
18d20 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a  omplete.  ^If a.
18d30 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
18d40 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e  tion fails, then
18d50 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73   SQLITE_NOMEM is
18d60 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
18d70 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
18d80 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68   do not parse th
18d90 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
18da0 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f   thus.** will no
18db0 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74  t detect syntact
18dc0 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74  ically incorrect
18dd0 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66   SQL..**.** ^(If
18de0 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20   SQLite has not 
18df0 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64  been initialized
18e00 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
18e10 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72  initialize()] pr
18e20 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b  ior .** to invok
18e30 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ing sqlite3_comp
18e40 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71  lete16() then sq
18e50 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
18e60 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
18e70 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
18e80 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  y sqlite3_comple
18e90 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74  te16().  If that
18ea0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
18eb0 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  fails,.** then t
18ec0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
18ed0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d  from sqlite3_com
18ee0 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62  plete16() will b
18ef0 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65  e non-zero.** re
18f00 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
18f10 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69  her or not the i
18f20 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70  nput SQL is comp
18f30 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  lete.)^.**.** Th
18f40 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
18f50 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20  te3_complete()] 
18f60 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
18f70 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
18f80 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
18f90 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
18fa0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
18fb0 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  6()] must be a z
18fc0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
18fd0 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  * UTF-16 string 
18fe0 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
18ff0 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rder..*/.int sql
19000 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
19010 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
19020 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
19030 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
19040 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
19050 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
19060 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
19070 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
19080 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a  USY Errors.**.**
19090 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75   ^The sqlite3_bu
190a0 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50  sy_handler(D,X,P
190b0 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  ) routine sets a
190c0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
190d0 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67  on X.** that mig
190e0 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
190f0 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68  th argument P wh
19100 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74  enever.** an att
19110 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
19120 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61 73  access a databas
19130 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74  e table associat
19140 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61  ed with.** [data
19150 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
19160 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20   D when another 
19170 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f  thread.** or pro
19180 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61 62  cess has the tab
19190 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68  le locked..** Th
191a0 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  e sqlite3_busy_h
191b0 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61  andler() interfa
191c0 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d  ce is used to im
191d0 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69  plement.** [sqli
191e0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
191f0 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20  ()] and [PRAGMA 
19200 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a  busy_timeout]..*
19210 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
19220 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
19230 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
19240 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74  _BUSY].** is ret
19250 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
19260 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
19270 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e  ing the lock.  ^
19280 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
19290 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
192a0 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
192b0 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20  llback might be 
192c0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
192d0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
192e0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
192f0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73  ument to the bus
19300 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  y handler is a c
19310 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
19320 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
19330 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
19340 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
19350 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
19360 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ).  ^The second 
19370 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
19380 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
19390 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
193a0 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
193b0 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
193c0 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
193d0 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  n invoked for th
193e0 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65  e same locking e
193f0 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
19400 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
19410 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
19420 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
19430 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
19440 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
19450 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
19460 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72  QLITE_BUSY] is r
19470 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68  eturned.** to th
19480 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a  e application..*
19490 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
194a0 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
194b0 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65  ero, then anothe
194c0 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20  r attempt.** is 
194d0 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74  made to access t
194e0 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
194f0 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74  the cycle repeat
19500 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65  s..**.** The pre
19510 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20  sence of a busy 
19520 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74  handler does not
19530 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
19540 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  it will be invok
19550 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65  ed.** when there
19560 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74   is lock content
19570 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ion. ^If SQLite 
19580 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20  determines that 
19590 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
195a0 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75  y.** handler cou
195b0 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64  ld result in a d
195c0 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c  eadlock, it will
195d0 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65   go ahead and re
195e0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
195f0 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70  Y].** to the app
19600 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64  lication instead
19610 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65   of invoking the
19620 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65   .** busy handle
19630 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
19640 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
19650 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
19660 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
19670 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
19680 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
19690 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
196a0 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
196b0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
196c0 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
196d0 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
196e0 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
196f0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
19700 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
19710 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
19720 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
19730 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
19740 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
19750 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
19760 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
19770 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
19780 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
19790 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
197a0 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
197b0 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
197c0 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
197d0 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
197e0 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
197f0 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
19800 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
19810 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
19820 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
19830 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
19840 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
19850 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
19860 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
19870 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
19880 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
19890 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
198a0 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
198b0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
198c0 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
198d0 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  is NULL..**.** ^
198e0 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
198f0 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
19900 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
19910 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61   for each.** [da
19920 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19930 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  n].  Setting a n
19940 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
19950 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72  clears any.** pr
19960 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e  eviously set han
19970 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74  dler.)^  ^Note t
19980 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  hat calling [sql
19990 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
199a0 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75  t()].** or evalu
199b0 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75  ating [PRAGMA bu
199c0 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69  sy_timeout=N] wi
199d0 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  ll change the.**
199e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e   busy handler an
199f0 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79  d thus clear any
19a00 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
19a10 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
19a20 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c  .** The busy cal
19a30 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74  lback should not
19a40 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e   take any action
19a50 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74  s which modify t
19a60 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
19a70 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
19a80 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
19a90 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68  handler.  In oth
19aa0 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65  er words,.** the
19ab0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
19ac0 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20   not reentrant. 
19ad0 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e   Any such action
19ae0 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75  s.** result in u
19af0 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
19b00 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79  r..** .** A busy
19b10 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
19b20 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  t close the data
19b30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
19b40 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20  ** or [prepared 
19b50 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
19b60 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
19b70 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74   handler..*/.int
19b80 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
19b90 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
19ba0 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  int(*)(void*,int
19bb0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
19bc0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
19bd0 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a  A Busy Timeout.*
19be0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
19bf0 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74  ne sets a [sqlit
19c00 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20  e3_busy_handler 
19c10 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20  | busy handler] 
19c20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66  that sleeps.** f
19c30 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61  or a specified a
19c40 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68  mount of time wh
19c50 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f  en a table is lo
19c60 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64  cked.  ^The hand
19c70 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65  ler.** will slee
19c80 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  p multiple times
19c90 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20   until at least 
19ca0 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
19cb0 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a  s of sleeping.**
19cc0 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65   have accumulate
19cd0 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65  d.  ^After at le
19ce0 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
19cf0 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
19d00 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65  g,.** the handle
19d10 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63  r returns 0 whic
19d20 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65  h causes [sqlite
19d30 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74  3_step()] to ret
19d40 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  urn.** [SQLITE_B
19d50 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  USY]..**.** ^Cal
19d60 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
19d70 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
19d80 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
19d90 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
19da0 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
19db0 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
19dc0 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
19dd0 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
19de0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
19df0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  r a particular.*
19e00 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
19e10 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67  ection] at any g
19e20 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66  iven moment.  If
19e30 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61   another busy ha
19e40 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66  ndler.** was def
19e50 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71  ined  (using [sq
19e60 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
19e70 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20  er()]) prior to 
19e80 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20  calling.** this 
19e90 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74  routine, that ot
19ea0 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
19eb0 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a   is cleared.)^.*
19ec0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20  *.** See also:  
19ed0 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d  [PRAGMA busy_tim
19ee0 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  eout].*/.int sql
19ef0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
19f00 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
19f10 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ms);../*.** CAPI
19f20 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63  3REF: Convenienc
19f30 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52  e Routines For R
19f40 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a  unning Queries.*
19f50 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c  *.** This is a l
19f60 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20  egacy interface 
19f70 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65  that is preserve
19f80 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
19f90 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
19fa0 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e  * Use of this in
19fb0 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
19fc0 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a  ecommended..**.*
19fd0 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
19fe0 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
19ff0 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
1a000 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
1a010 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
1a020 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1a030 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
1a040 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1a050 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
1a060 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
1a070 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
1a080 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
1a090 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
1a0a0 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
1a0b0 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
1a0c0 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
1a0d0 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
1a0e0 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
1a0f0 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
1a100 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
1a110 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
1a120 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
1a130 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
1a140 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1a150 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
1a160 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1a170 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
1a180 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1a190 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
1a1a0 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
1a1b0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
1a1c0 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
1a1d0 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
1a1e0 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
1a1f0 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
1a200 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
1a210 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
1a220 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
1a230 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
1a240 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
1a250 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
1a260 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
1a270 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
1a280 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
1a290 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
1a2a0 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
1a2b0 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
1a2c0 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
1a2d0 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
1a2e0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1a2f0 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
1a300 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
1a310 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1a320 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
1a330 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
1a340 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
1a350 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
1a360 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
1a370 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
1a380 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
1a390 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
1a3a0 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
1a3b0 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
1a3c0 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
1a3d0 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
1a3e0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
1a3f0 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
1a400 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70  ** ^(As an examp
1a410 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  le of the result
1a420 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73   table format, s
1a430 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72  uppose a query r
1a440 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66  esult.** is as f
1a450 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1a460 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1a470 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
1a480 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
1a490 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
1a4a0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
1a4b0 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
1a4c0 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
1a4d0 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
1a4e0 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
1a4f0 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
1a500 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1a510 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  uote>.**.** Ther
1a520 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e  e are two column
1a530 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65   (M==2) and thre
1a540 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20  e rows (N==3).  
1a550 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75  Thus the.** resu
1a560 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65  lt table has 8 e
1a570 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65  ntries.  Suppose
1a580 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1a590 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  e is stored.** i
1a5a0 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73  n an array names
1a5b0 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e   azResult.  Then
1a5c0 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20   azResult holds 
1a5d0 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a  this content:.**
1a5e0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1a5f0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
1a600 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
1a610 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
1a620 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1a630 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
1a640 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1a650 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
1a660 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1a670 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
1a680 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
1a690 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
1a6a0 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
1a6b0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
1a6c0 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
1a6d0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1a6e0 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
1a6f0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1a700 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
1a710 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1a720 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
1a730 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1a740 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
1a750 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
1a760 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
1a770 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
1a780 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
1a790 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
1a7a0 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
1a7b0 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
1a7c0 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
1a7d0 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
1a7e0 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
1a7f0 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
1a800 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
1a810 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
1a820 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61  e application ha
1a830 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
1a840 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  the result from 
1a850 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1a860 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20  e(),.** it must 
1a870 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20  pass the result 
1a880 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f  table pointer to
1a890 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1a8a0 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
1a8b0 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
1a8c0 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
1a8d0 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
1a8e0 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
1a8f0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
1a900 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
1a910 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
1a920 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
1a930 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
1a940 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
1a950 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
1a960 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
1a970 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
1a980 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1a990 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
1a9a0 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
1a9b0 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
1a9c0 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
1a9d0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1a9e0 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
1a9f0 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
1aa00 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
1aa10 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
1aa20 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
1aa30 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1aa40 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
1aa50 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
1aa60 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
1aa70 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
1aa80 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
1aa90 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
1aaa0 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
1aab0 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
1aac0 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
1aad0 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
1aae0 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
1aaf0 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
1ab00 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
1ab10 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
1ab20 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
1ab30 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
1ab40 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
1ab50 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1ab60 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a  errcode()] or.**
1ab70 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1ab80 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
1ab90 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
1aba0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1abb0 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
1abc0 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
1abd0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1abe0 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
1abf0 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
1ac00 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
1ac10 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
1ac20 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
1ac30 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
1ac40 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
1ac50 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
1ac60 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
1ac70 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
1ac80 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
1ac90 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1aca0 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
1acb0 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
1acc0 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
1acd0 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
1ace0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
1acf0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
1ad00 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
1ad10 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
1ad20 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
1ad30 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
1ad40 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
1ad50 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1ad60 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65  s are work-alike
1ad70 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66  s of the "printf
1ad80 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75  ()" family of fu
1ad90 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20  nctions.** from 
1ada0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
1adb0 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ibrary..**.** ^T
1adc0 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  he sqlite3_mprin
1add0 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  tf() and sqlite3
1ade0 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _vmprintf() rout
1adf0 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72  ines write their
1ae00 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
1ae10 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
1ae20 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
1ae30 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65  alloc()]..** The
1ae40 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
1ae50 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72  d by these two r
1ae60 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62  outines should b
1ae70 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79  e.** released by
1ae80 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1ae90 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e  ].  ^Both routin
1aea0 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e  es return a.** N
1aeb0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b  ULL pointer if [
1aec0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1aed0 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  ] is unable to a
1aee0 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a  llocate enough.*
1aef0 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  * memory to hold
1af00 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
1af10 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tring..**.** ^(T
1af20 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  he sqlite3_snpri
1af30 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
1af40 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70   similar to "snp
1af50 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a  rintf()" from.**
1af60 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
1af70 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65  library.  The re
1af80 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20  sult is written 
1af90 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66  into the.** buff
1afa0 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74  er supplied as t
1afb0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1afc0 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69  ter whose size i
1afd0 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68  s given by.** th
1afe0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1aff0 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  r. Note that the
1b000 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a   order of the.**
1b010 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d   first two param
1b020 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65  eters is reverse
1b030 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28  d from snprintf(
1b040 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e  ).)^  This is an
1b050 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61  .** historical a
1b060 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e  ccident that can
1b070 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74  not be fixed wit
1b080 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a  hout breaking.**
1b090 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
1b0a0 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74  tibility.  ^(Not
1b0b0 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69  e also that sqli
1b0c0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1b0d0 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  * returns a poin
1b0e0 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65  ter to its buffe
1b0f0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
1b100 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
1b110 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c  aracters actuall
1b120 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  y written into t
1b130 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65  he buffer.)^  We
1b140 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74   admit that.** t
1b150 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
1b160 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20  racters written 
1b170 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20  would be a more 
1b180 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a  useful return.**
1b190 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61   value but we ca
1b1a0 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20  nnot change the 
1b1b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1b1c0 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
1b1d0 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68  tf().** now with
1b1e0 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d  out breaking com
1b1f0 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
1b200 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68  * ^As long as th
1b210 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73  e buffer size is
1b220 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
1b230 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  ro, sqlite3_snpr
1b240 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e  intf().** guaran
1b250 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75  tees that the bu
1b260 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a  ffer is always z
1b270 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
1b280 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70   ^The first.** p
1b290 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20  arameter "n" is 
1b2a0 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f  the total size o
1b2b0 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e  f the buffer, in
1b2c0 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f  cluding space fo
1b2d0 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65  r.** the zero te
1b2e0 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68  rminator.  So th
1b2f0 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
1b300 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
1b310 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
1b320 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
1b330 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
1b340 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73   ^The sqlite3_vs
1b350 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
1b360 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76  e is a varargs v
1b370 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  ersion of sqlite
1b380 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a  3_snprintf()..**
1b390 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1b3a0 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
1b3b0 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
1b3c0 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
1b3d0 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
1b3e0 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
1b3f0 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
1b400 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
1b410 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
1b420 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20  tf() formatting 
1b430 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20  options apply.  
1b440 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65  In addition, the
1b450 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71  re.** is are "%q
1b460 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a  ", "%Q", and "%z
1b470 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  " options..**.**
1b480 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e   ^(The %q option
1b490 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69   works like %s i
1b4a0 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69  n that it substi
1b4b0 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d  tutes a nul-term
1b4c0 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
1b4d0 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65   from the argume
1b4e0 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71  nt list.  But %q
1b4f0 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76   also doubles ev
1b500 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74  ery '\'' charact
1b510 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73  er..** %q is des
1b520 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e  igned for use in
1b530 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69  side a string li
1b540 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75  teral.)^  By dou
1b550 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
1b560 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
1b570 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
1b580 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
1b590 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
1b5a0 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
1b5b0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
1b5c0 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d  r example, assum
1b5d0 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72  e the string var
1b5e0 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74  iable zText cont
1b5f0 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c  ains text as fol
1b600 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1b610 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1b620 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20    char *zText = 
1b630 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  "It's a happy da
1b640 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!";.** </pre></
1b650 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1b660 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68  * One can use th
1b670 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51  is text in an SQ
1b680 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66  L statement as f
1b690 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1b6a0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1b6b0 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1b6c0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1b6d0 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1b6e0 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29  ble VALUES('%q')
1b6f0 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
1b700 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
1b710 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
1b720 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
1b730 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
1b740 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1b750 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
1b760 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e   %q format strin
1b770 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27  g is used, the '
1b780 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e  \'' character in
1b790 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63   zText.** is esc
1b7a0 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  aped and the SQL
1b7b0 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73   generated is as
1b7c0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1b7d0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1b7e0 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
1b7f0 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
1b800 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64  'It''s a happy d
1b810 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!').** </pre><
1b820 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1b830 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65  ** This is corre
1b840 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64  ct.  Had we used
1b850 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %s instead of %
1b860 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64  q, the generated
1b870 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61   SQL.** would ha
1b880 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74  ve looked like t
1b890 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
1b8a0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1b8b0 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
1b8c0 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73  le1 VALUES('It's
1b8d0 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b   a happy day!');
1b8e0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1b8f0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1b900 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c  is second exampl
1b910 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74  e is an SQL synt
1b920 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20  ax error.  As a 
1b930 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75  general rule you
1b940 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79   should.** alway
1b950 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64  s use %q instead
1b960 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65   of %s when inse
1b970 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20  rting text into 
1b980 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
1b990 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51  ..**.** ^(The %Q
1b9a0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1b9b0 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20  ke %q except it 
1b9c0 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65  also adds single
1b9d0 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a   quotes around.*
1b9e0 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66  * the outside of
1b9f0 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e   the total strin
1ba00 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79  g.  Additionally
1ba10 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  , if the paramet
1ba20 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67  er in the.** arg
1ba30 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20  ument list is a 
1ba40 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51  NULL pointer, %Q
1ba50 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65   substitutes the
1ba60 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69   text "NULL" (wi
1ba70 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20  thout.** single 
1ba80 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20  quotes).)^  So, 
1ba90 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65  for example, one
1baa0 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a   could say:.**.*
1bab0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1bac0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
1bad0 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
1bae0 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
1baf0 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25  O table VALUES(%
1bb00 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  Q)", zText);.** 
1bb10 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
1bb20 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
1bb30 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
1bb40 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
1bb50 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1bb60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
1bb70 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65  above will rende
1bb80 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20  r a correct SQL 
1bb90 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
1bba0 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c   zSQL.** variabl
1bbb0 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54  e even if the zT
1bbc0 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20  ext variable is 
1bbd0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1bbe0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22  **.** ^(The "%z"
1bbf0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1bc00 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25  on works like "%
1bc10 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a  s" but with the.
1bc20 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74  ** addition that
1bc30 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e   after the strin
1bc40 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20  g has been read 
1bc50 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a  and copied into.
1bc60 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b  ** the result, [
1bc70 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1bc80 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  is called on the
1bc90 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e   input string.)^
1bca0 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .*/.char *sqlite
1bcb0 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  3_mprintf(const 
1bcc0 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72  char*,...);.char
1bcd0 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   *sqlite3_vmprin
1bce0 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  tf(const char*, 
1bcf0 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a  va_list);.char *
1bd00 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1bd10 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
1bd20 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68   char*, ...);.ch
1bd30 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70  ar *sqlite3_vsnp
1bd40 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
1bd50 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
1bd60 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  list);../*.** CA
1bd70 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
1bd80 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
1bd90 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
1bda0 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
1bdb0 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
1bdc0 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
1bdd0 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
1bde0 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
1bdf0 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
1be00 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
1be10 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
1be20 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
1be30 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
1be40 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
1be50 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
1be60 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
1be70 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
1be80 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
1be90 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
1bea0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions..**.** ^Th
1beb0 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
1bec0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
1bed0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1bee0 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
1bef0 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
1bf00 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
1bf10 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
1bf20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
1bf30 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
1bf40 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
1bf50 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
1bf60 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
1bf70 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
1bf80 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49  ULL pointer.  ^I
1bf90 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1bfa0 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
1bfb0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
1bfc0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
1bfd0 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
1bfe0 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
1bff0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1c000 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1c010 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75  _malloc64(N) rou
1c020 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20  tine works just 
1c030 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  like.** sqlite3_
1c040 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74  malloc(N) except
1c050 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e   that N is an un
1c060 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e  signed 64-bit in
1c070 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
1c080 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d   of a signed 32-
1c090 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  bit integer..**.
1c0a0 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
1c0b0 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
1c0c0 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
1c0d0 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
1c0e0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
1c0f0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
1c100 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
1c110 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
1c120 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
1c130 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e  ht be reused.  ^
1c140 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
1c150 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
1c160 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
1c170 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
1c180 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
1c190 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
1c1a0 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
1c1b0 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
1c1c0 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
1c1d0 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
1c1e0 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
1c1f0 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
1c200 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
1c210 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
1c220 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
1c230 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
1c240 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
1c250 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
1c260 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
1c270 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
1c280 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
1c290 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
1c2a0 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
1c2b0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
1c2c0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1c2d0 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
1c2e0 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
1c2f0 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
1c300 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
1c310 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1c320 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1c330 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  loc()..**.** ^Th
1c340 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
1c350 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  c(X,N) interface
1c360 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
1c370 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
1c380 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1c390 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73   X to be at leas
1c3a0 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49  t N bytes..** ^I
1c3b0 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65  f the X paramete
1c3c0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1c3d0 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20  lloc(X,N).** is 
1c3e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1c3f0 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
1c400 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
1c410 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1c420 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a  te3_malloc(N)..*
1c430 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61  * ^If the N para
1c440 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1c450 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73  _realloc(X,N) is
1c460 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
1c470 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
1c480 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
1c490 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
1c4a0 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1c4b0 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71  _free(X)..** ^sq
1c4c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1c4d0 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  N) returns a poi
1c4e0 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
1c4f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
1c500 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
1c510 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
1c520 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65  LL if insufficie
1c530 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61  nt memory is ava
1c540 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d  ilable..** ^If M
1c550 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
1c560 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1c570 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
1c580 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
1c590 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1c5a0 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
1c5b0 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
1c5c0 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
1c5d0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1c5e0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1c5f0 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61   and the prior a
1c600 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65  llocation is fre
1c610 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  ed..** ^If sqlit
1c620 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1c630 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
1c640 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20   N is positive, 
1c650 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f  then the.** prio
1c660 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
1c670 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
1c680 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
1c690 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74  alloc64(X,N) int
1c6a0 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68  erfaces works th
1c6b0 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c  e same as.** sql
1c6c0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1c6d0 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20  ) except that N 
1c6e0 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69  is a 64-bit unsi
1c6f0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73  gned integer ins
1c700 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d  tead.** of a 32-
1c710 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
1c720 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20  er..**.** ^If X 
1c730 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  is a memory allo
1c740 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c  cation previousl
1c750 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
1c760 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1c770 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ,.** sqlite3_mal
1c780 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33  loc64(), sqlite3
1c790 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73  _realloc(), or s
1c7a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1c7b0 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  (), then.** sqli
1c7c0 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74  te3_msize(X) ret
1c7d0 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66  urns the size of
1c7e0 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c   that memory all
1c7f0 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73  ocation in bytes
1c800 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20  ..** ^The value 
1c810 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1c820 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67  te3_msize(X) mig
1c830 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61  ht be larger tha
1c840 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20  n the number.** 
1c850 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74  of bytes request
1c860 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c  ed when X was al
1c870 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20  located.  ^If X 
1c880 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1c890 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  r then.** sqlite
1c8a0 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72  3_msize(X) retur
1c8b0 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70  ns zero.  If X p
1c8c0 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69  oints to somethi
1c8d0 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a  ng that is not.*
1c8e0 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  * the beginning 
1c8f0 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  of memory alloca
1c900 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70  tion, or if it p
1c910 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65  oints to a forme
1c920 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d  rly.** valid mem
1c930 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
1c940 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e  hat has now been
1c950 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65   freed, then the
1c960 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
1c970 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
1c980 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
1c990 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66  d possibly harmf
1c9a0 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ul..**.** ^The m
1c9b0 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
1c9c0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
1c9d0 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  (), sqlite3_real
1c9e0 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  loc(),.** sqlite
1c9f0 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e  3_malloc64(), an
1ca00 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
1ca10 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  c64().** is alwa
1ca20 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
1ca30 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
1ca40 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f   boundary, or to
1ca50 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75   a.** 4 byte bou
1ca60 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51  ndary if the [SQ
1ca70 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47  LITE_4_BYTE_ALIG
1ca80 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70  NED_MALLOC] comp
1ca90 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
1caa0 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
1cab0 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
1cac0 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
1cad0 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
1cae0 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
1caf0 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
1cb00 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
1cb10 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
1cb20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
1cb30 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
1cb40 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
1cb50 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
1cb60 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
1cb70 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
1cb80 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
1cb90 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
1cba0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
1cbb0 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
1cbc0 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
1cbd0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
1cbe0 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73  .10, the Windows
1cbf0 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
1cc00 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68  yer called.** th
1cc10 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
1cc20 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
1cc30 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
1cc40 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
1cc50 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
1cc60 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
1cc70 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
1cc80 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
1cc90 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
1cca0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
1ccb0 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
1ccc0 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
1ccd0 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
1cce0 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65  tion errors were
1ccf0 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
1cd00 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f  * they were repo
1cd10 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
1cd20 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
1cd30 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
1cd40 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
1cd50 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
1cd60 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
1cd70 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
1cd80 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1cd90 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1cda0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
1cdb0 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
1cdc0 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
1cdd0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
1cde0 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
1cdf0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1ce00 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
1ce10 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1ce20 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
1ce30 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
1ce40 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
1ce50 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
1ce60 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
1ce70 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
1ce80 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
1ce90 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
1cea0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
1ceb0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1cec0 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
1ced0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
1cee0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
1cef0 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  _malloc(int);.vo
1cf00 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
1cf10 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e  oc64(sqlite3_uin
1cf20 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  t64);.void *sqli
1cf30 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
1cf40 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73  *, int);.void *s
1cf50 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1cf60 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f  (void*, sqlite3_
1cf70 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71  uint64);.void sq
1cf80 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
1cf90 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  );.sqlite3_uint6
1cfa0 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  4 sqlite3_msize(
1cfb0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1cfc0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
1cfd0 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
1cfe0 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  tics.**.** SQLit
1cff0 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65  e provides these
1d000 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20   two interfaces 
1d010 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e  for reporting on
1d020 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f   the status.** o
1d030 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
1d040 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
1d050 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20  e3_free()], and 
1d060 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1d070 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c  ()].** routines,
1d080 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20   which form the 
1d090 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
1d0a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
1d0b0 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  stem..**.** ^The
1d0c0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1d0d0 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65  _used()] routine
1d0e0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1d0f0 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20  ber of bytes.** 
1d100 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e  of memory curren
1d110 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  tly outstanding 
1d120 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f  (malloced but no
1d130 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68  t freed)..** ^Th
1d140 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
1d150 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72  y_highwater()] r
1d160 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
1d170 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61  he maximum.** va
1d180 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
1d190 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73  memory_used()] s
1d1a0 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61  ince the high-wa
1d1b0 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20  ter mark.** was 
1d1c0 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68  last reset.  ^Th
1d1d0 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
1d1e0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d by [sqlite3_me
1d1f0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64  mory_used()] and
1d200 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
1d210 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1d220 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65   include any ove
1d230 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62  rhead.** added b
1d240 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20  y SQLite in its 
1d250 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1d260 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
1d270 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74  c()],.** but not
1d280 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20   overhead added 
1d290 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72  by the any under
1d2a0 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62  lying system lib
1d2b0 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  rary.** routines
1d2c0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d   that [sqlite3_m
1d2d0 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c  alloc()] may cal
1d2e0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
1d2f0 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20  mory high-water 
1d300 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f  mark is reset to
1d310 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
1d320 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  ue of.** [sqlite
1d330 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1d340 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
1d350 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  the parameter to
1d360 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
1d370 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1d380 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20   is true.  ^The 
1d390 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
1d3a0 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  * by [sqlite3_me
1d3b0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31  mory_highwater(1
1d3c0 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77  )] is the high-w
1d3d0 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69  ater mark.** pri
1d3e0 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e  or to the reset.
1d3f0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
1d400 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
1d410 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c  _used(void);.sql
1d420 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1d430 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1d440 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
1d450 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
1d460 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
1d470 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
1d480 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  tor.**.** SQLite
1d490 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
1d4a0 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
1d4b0 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
1d4c0 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
1d4d0 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
1d4e0 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
1d4f0 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
1d500 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
1d510 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
1d520 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
1d530 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
1d540 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
1d550 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
1d560 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
1d570 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
1d580 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
1d590 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
1d5a0 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
1d5b0 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
1d5c0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
1d5d0 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
1d5e0 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
1d5f0 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
1d600 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73   ^A call to this
1d610 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
1d620 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  N bytes of rando
1d630 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
1d640 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70  r P..** ^The P p
1d650 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20  arameter can be 
1d660 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1d670 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72  **.** ^If this r
1d680 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62  outine has not b
1d690 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63  een previously c
1d6a0 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20  alled or if the 
1d6b0 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c  previous.** call
1d6c0 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e   had N less than
1d6d0 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70   one or a NULL p
1d6e0 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68  ointer for P, th
1d6f0 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a  en the PRNG is.*
1d700 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72  * seeded using r
1d710 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
1d720 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ed from the xRan
1d730 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
1d740 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74  f.** the default
1d750 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1d760 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  bject..** ^If th
1d770 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
1d780 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
1d790 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72  had an N of 1 or
1d7a0 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e   more and a.** n
1d7b0 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74  on-NULL P then t
1d7c0 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  he pseudo-random
1d7d0 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65  ness is generate
1d7e0 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20  d.** internally 
1d7f0 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f  and without reco
1d800 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c  urse to the [sql
1d810 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f  ite3_vfs] xRando
1d820 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e  mness.** method.
1d830 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
1d840 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
1d850 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
1d860 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1d870 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
1d880 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
1d890 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  ks.**.** ^This r
1d8a0 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73  outine registers
1d8b0 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   an authorizer c
1d8c0 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70  allback with a p
1d8d0 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
1d8e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d8f0 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20  n], supplied in 
1d900 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
1d910 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68  nt..** ^The auth
1d920 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1d930 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51  is invoked as SQ
1d940 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
1d950 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a   being compiled.
1d960 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
1d970 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
1d980 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74   variants [sqlit
1d990 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1d9a0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
1d9b0 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b  epare16()] and [
1d9c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1d9d0 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61  6_v2()].  ^At va
1d9e0 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20  rious.** points 
1d9f0 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  during the compi
1da00 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20  lation process, 
1da10 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e  as logic is bein
1da20 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20  g created.** to 
1da30 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
1da40 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74  actions, the aut
1da50 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1da60 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a   is invoked to.*
1da70 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61  * see if those a
1da80 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77  ctions are allow
1da90 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72  ed.  ^The author
1daa0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68  izer callback sh
1dab0 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
1dac0 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c  SQLITE_OK] to al
1dad0 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20  low the action, 
1dae0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
1daf0 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a  to disallow the.
1db00 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69  ** specific acti
1db10 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65  on but allow the
1db20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1db30 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  o continue to be
1db40 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72  .** compiled, or
1db50 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74   [SQLITE_DENY] t
1db60 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69  o cause the enti
1db70 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  re SQL statement
1db80 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74   to be.** reject
1db90 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ed with an error
1dba0 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  .  ^If the autho
1dbb0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
1dbc0 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61  eturns.** any va
1dbd0 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  lue other than [
1dbe0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
1dbf0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
1dc00 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a  [SQLITE_DENY].**
1dc10 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74   then the [sqlit
1dc20 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1dc30 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
1dc40 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
1dc50 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  ed.** the author
1dc60 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
1dc70 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
1dc80 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  sage..**.** When
1dc90 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1dca0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
1dcb0 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  ], that means th
1dcc0 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72  e operation.** r
1dcd0 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20  equested is ok. 
1dce0 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62   ^When the callb
1dcf0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1dd00 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
1dd10 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1dd20 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
1dd30 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
1dd40 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a   triggered the.*
1dd50 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  * authorizer wil
1dd60 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
1dd70 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70  rror message exp
1dd80 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20  laining that.** 
1dd90 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64  access is denied
1dda0 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  . .**.** ^The fi
1ddb0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
1ddc0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1ddd0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
1dde0 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a  py of the third.
1ddf0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
1de00 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
1de10 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74  authorizer() int
1de20 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63  erface. ^The sec
1de30 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ond parameter.**
1de40 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1de50 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b   is an integer [
1de60 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63  SQLITE_COPY | ac
1de70 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20  tion code] that 
1de80 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
1de90 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69   particular acti
1dea0 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
1deb0 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20  zed. ^The third 
1dec0 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61  through sixth pa
1ded0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74  rameters.** to t
1dee0 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20  he callback are 
1def0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1df00 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e  strings that con
1df10 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a  tain additional.
1df20 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74  ** details about
1df30 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62   the action to b
1df40 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  e authorized..**
1df50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
1df60 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
1df70 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20  TE_READ].** and 
1df80 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1df90 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e  urns [SQLITE_IGN
1dfa0 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ORE] then the.**
1dfb0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1dfc0 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20  ment] statement 
1dfd0 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74  is constructed t
1dfe0 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20  o substitute.** 
1dff0 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
1e000 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
1e010 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
1e020 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65  ould have.** bee
1e030 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54  n read if [SQLIT
1e040 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72  E_OK] had been r
1e050 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53  eturned.  The [S
1e060 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a  QLITE_IGNORE].**
1e070 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75   return can be u
1e080 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75  sed to deny an u
1e090 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63  ntrusted user ac
1e0a0 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75  cess to individu
1e0b0 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66  al.** columns of
1e0c0 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66   a table..** ^If
1e0d0 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
1e0e0 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45   is [SQLITE_DELE
1e0f0 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  TE] and the call
1e100 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
1e110 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
1e120 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45  then the [DELETE
1e130 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63  ] operation proc
1e140 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20  eeds but the.** 
1e150 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69  [truncate optimi
1e160 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62  zation] is disab
1e170 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73  led and all rows
1e180 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64   are deleted ind
1e190 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  ividually..**.**
1e1a0 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69   An authorizer i
1e1b0 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c  s used when [sql
1e1c0 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
1e1d0 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c  reparing].** SQL
1e1e0 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d   statements from
1e1f0 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f   an untrusted so
1e200 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20  urce, to ensure 
1e210 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61  that the SQL sta
1e220 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f  tements.** do no
1e230 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20  t try to access 
1e240 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f  data they are no
1e250 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65  t allowed to see
1e260 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64  , or that they d
1e270 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20  o not.** try to 
1e280 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75  execute maliciou
1e290 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  s statements tha
1e2a0 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74  t damage the dat
1e2b0 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  abase.  For.** e
1e2c0 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
1e2d0 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77  cation may allow
1e2e0 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72   a user to enter
1e2f0 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51   arbitrary.** SQ
1e300 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76  L queries for ev
1e310 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61  aluation by a da
1e320 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65  tabase.  But the
1e330 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
1e340 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68  s.** not want th
1e350 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c  e user to be abl
1e360 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72  e to make arbitr
1e370 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ary changes to t
1e380 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  he.** database. 
1e390 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   An authorizer c
1e3a0 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74  ould then be put
1e3b0 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20   in place while 
1e3c0 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65  the.** user-ente
1e3d0 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67  red SQL is being
1e3e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e3f0 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68  e | prepared] th
1e400 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20  at.** disallows 
1e410 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70  everything excep
1e420 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  t [SELECT] state
1e430 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  ments..**.** App
1e440 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e  lications that n
1e450 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53  eed to process S
1e460 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65  QL from untruste
1e470 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67  d sources.** mig
1e480 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72  ht also consider
1e490 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72   lowering resour
1e4a0 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20  ce limits using 
1e4b0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
1e4c0 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e  ].** and limitin
1e4d0 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20  g database size 
1e4e0 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70  using the [max_p
1e4f0 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
1e500 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69  MA].** in additi
1e510 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61  on to using an a
1e520 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a  uthorizer..**.**
1e530 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65   ^(Only a single
1e540 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20   authorizer can 
1e550 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61  be in place on a
1e560 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1e570 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d  tion.** at a tim
1e580 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  e.  Each call to
1e590 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1e5a0 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65  horizer override
1e5b0 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75  s the.** previou
1e5c0 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61  s call.)^  ^Disa
1e5d0 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ble the authoriz
1e5e0 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67  er by installing
1e5f0 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b   a NULL callback
1e600 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  ..** The authori
1e610 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
1e620 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
1e630 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
1e640 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
1e650 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
1e660 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
1e670 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1e680 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
1e690 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68  invoked the auth
1e6a0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e  orizer callback.
1e6b0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
1e6c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1e6d0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
1e6e0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
1e6f0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
1e700 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e710 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
1e720 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
1e730 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
1e740 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b  h..**.** ^When [
1e750 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1e760 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f  v2()] is used to
1e770 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65   prepare a state
1e780 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61  ment, the.** sta
1e790 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20  tement might be 
1e7a0 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69  re-prepared duri
1e7b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
1e7c0 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a  ()] due to a .**
1e7d0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20   schema change. 
1e7e0 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c   Hence, the appl
1e7f0 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65  ication should e
1e800 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a  nsure that the.*
1e810 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72  * correct author
1e820 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
1e830 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64  mains in place d
1e840 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  uring the [sqlit
1e850 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a  e3_step()]..**.*
1e860 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65  * ^Note that the
1e870 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1e880 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1e890 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b  only during.** [
1e8a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1e8b0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
1e8c0 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69  ts.  Authorizati
1e8d0 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72  on is not.** per
1e8e0 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74  formed during st
1e8f0 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69  atement evaluati
1e900 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73  on in [sqlite3_s
1e910 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a  tep()], unless.*
1e920 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74  * as stated in t
1e930 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61  he previous para
1e940 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73  graph, sqlite3_s
1e950 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a  tep() invokes.**
1e960 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1e970 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61  _v2() to reprepa
1e980 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61  re a statement a
1e990 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68  fter a schema ch
1e9a0 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ange..*/.int sql
1e9b0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1e9c0 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  zer(.  sqlite3*,
1e9d0 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28  .  int (*xAuth)(
1e9e0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
1e9f0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1ea00 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
1ea10 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f  nst char*),.  vo
1ea20 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b  id *pUserData.);
1ea30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ea40 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74  : Authorizer Ret
1ea50 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  urn Codes.**.** 
1ea60 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
1ea70 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
1ea80 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1ea90 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74  k function] must
1eaa0 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65  .** return eithe
1eab0 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  r [SQLITE_OK] or
1eac0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77   one of these tw
1ead0 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f  o constants in o
1eae0 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  rder.** to signa
1eaf0 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72  l SQLite whether
1eb00 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69   or not the acti
1eb10 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e  on is permitted.
1eb20 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71    See the.** [sq
1eb30 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1eb40 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
1eb50 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  r documentation]
1eb60 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
1eb70 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
1eb80 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
1eb90 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73  SQLITE_IGNORE is
1eba0 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20   also used as a 
1ebb0 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75  [conflict resolu
1ebc0 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65  tion mode].** re
1ebd0 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 20  turned from the 
1ebe0 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e  [sqlite3_vtab_on
1ebf0 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74  _conflict()] int
1ec00 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69  erface..*/.#defi
1ec10 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20  ne SQLITE_DENY  
1ec20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68   1   /* Abort th
1ec30 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1ec40 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f  with an error */
1ec50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ec60 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f  IGNORE 2   /* Do
1ec70 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73  n't allow access
1ec80 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65  , but don't gene
1ec90 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f  rate an error */
1eca0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ecb0 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74  : Authorizer Act
1ecc0 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ion Codes.**.** 
1ecd0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
1ece0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
1ecf0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
1ed00 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
1ed10 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  nction.** that i
1ed20 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74  s invoked to aut
1ed30 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53  horize certain S
1ed40 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
1ed50 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
1ed60 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
1ed70 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
1ed80 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
1ed90 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
1eda0 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
1edb0 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
1edc0 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
1edd0 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
1ede0 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
1edf0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1ee00 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
1ee10 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
1ee20 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
1ee30 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
1ee40 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
1ee50 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a  ation is to be.*
1ee60 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
1ee70 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
1ee80 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
1ee90 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
1eea0 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
1eeb0 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
1eec0 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
1eed0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
1eee0 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
1eef0 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
1ef00 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1ef10 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20  ter.  ^(The 5th 
1ef20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1ef30 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63  .** authorizer c
1ef40 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
1ef50 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
1ef60 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65  ase ("main", "te
1ef70 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66  mp",.** etc.) if
1ef80 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20   applicable.)^  
1ef90 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74  ^The 6th paramet
1efa0 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
1efb0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
1efc0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1efd0 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74  the inner-most t
1efe0 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74  rigger or view t
1eff0 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62  hat is responsib
1f000 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63  le for.** the ac
1f010 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20  cess attempt or 
1f020 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63  NULL if this acc
1f030 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64  ess attempt is d
1f040 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20  irectly from.** 
1f050 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
1f060 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  de..*/./********
1f070 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f080 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f090 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
1f0a0 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
1f0b0 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
1f0c0 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
1f0d0 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
1f0e0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1f0f0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1f100 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f110 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
1f120 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
1f130 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f140 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f150 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f160 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
1f170 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
1f180 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1f190 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f1a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f1b0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
1f1c0 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
1f1d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1f1e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f1f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f200 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
1f210 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
1f220 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1f230 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1f240 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f250 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
1f260 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
1f270 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1f280 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f290 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1f2a0 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
1f2b0 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
1f2c0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1f2d0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1f2e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1f2f0 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
1f300 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
1f310 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1f320 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f330 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
1f340 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
1f350 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
1f360 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1f370 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1f380 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1f390 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
1f3a0 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
1f3b0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1f3c0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1f3d0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1f3e0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
1f3f0 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
1f400 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1f410 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1f420 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1f430 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
1f440 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
1f450 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1f460 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1f470 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1f480 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
1f490 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1f4a0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f4b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f4c0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1f4d0 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
1f4e0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1f4f0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1f500 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f510 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
1f520 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
1f530 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1f540 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f550 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f560 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
1f570 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
1f580 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1f590 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1f5a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f5b0 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
1f5c0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
1f5d0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1f5e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f5f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f600 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
1f610 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
1f620 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f630 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f640 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f650 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
1f660 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
1f670 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
1f680 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
1f690 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f6a0 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
1f6b0 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
1f6c0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
1f6d0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
1f6e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f6f0 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
1f700 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
1f710 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
1f720 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f730 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f740 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
1f750 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65       22   /* Ope
1f760 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c  ration       NUL
1f770 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f780 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
1f790 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
1f7a0 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
1f7b0 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
1f7c0 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
1f7d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
1f7e0 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
1f7f0 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
1f800 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
1f810 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f820 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
1f830 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
1f840 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
1f850 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
1f860 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1f870 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
1f880 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
1f890 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
1f8a0 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
1f8b0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1f8c0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
1f8d0 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
1f8e0 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
1f8f0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1f900 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1f910 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
1f920 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
1f930 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
1f940 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1f950 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f960 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1f970 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
1f980 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1f990 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
1f9a0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1f9b0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
1f9c0 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
1f9d0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1f9e0 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
1f9f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1fa00 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
1fa10 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
1fa20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
1fa30 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d      Function Nam
1fa40 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e   */.#define S
1fa50 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20  QLITE_SAVEPOINT 
1fa60 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20             32   
1fa70 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
1fa80 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d     Savepoint Nam
1fa90 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e  */.#define SQ
1faa0 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20  LITE_COPY       
1fab0 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
1fac0 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  * No longer used
1fad0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1fae0 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20 20  TE_RECURSIVE    
1faf0 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a 20          33   /* 
1fb00 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1fb10 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1fb20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
1fb30 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
1fb40 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
1fb50 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
1fb60 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65  routines registe
1fb70 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
1fb80 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65  ions that can be
1fb90 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61   used for.** tra
1fba0 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69  cing and profili
1fbb0 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
1fbc0 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
1fbd0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ts..**.** ^The c
1fbe0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1fbf0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
1fc00 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69  qlite3_trace() i
1fc10 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20  s invoked at.** 
1fc20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68  various times wh
1fc30 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  en an SQL statem
1fc40 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e  ent is being run
1fc50 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   by [sqlite3_ste
1fc60 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  p()]..** ^The sq
1fc70 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
1fc80 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1fc90 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72  d with a UTF-8 r
1fca0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a  endering of the.
1fcb0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1fcc0 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61   text as the sta
1fcd0 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67  tement first beg
1fce0 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  ins executing..*
1fcf0 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73  * ^(Additional s
1fd00 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
1fd10 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f  allbacks might o
1fd20 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20  ccur.** as each 
1fd30 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f  triggered subpro
1fd40 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e  gram is entered.
1fd50 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20    The callbacks 
1fd60 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20  for triggers.** 
1fd70 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20  contain a UTF-8 
1fd80 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74  SQL comment that
1fd90 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20   identifies the 
1fda0 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a  trigger.)^.**.**
1fdb0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41   The [SQLITE_TRA
1fdc0 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63  CE_SIZE_LIMIT] c
1fdd0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
1fde0 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
1fdf0 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c  o limit.** the l
1fe00 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20  ength of [bound 
1fe10 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e  parameter] expan
1fe20 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70  sion in the outp
1fe30 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72  ut of sqlite3_tr
1fe40 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ace()..**.** ^Th
1fe50 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
1fe60 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
1fe70 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  y sqlite3_profil
1fe80 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
1fe90 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74  * as each SQL st
1fea0 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
1feb0 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
1fec0 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
1fed0 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  s.** the origina
1fee0 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  l statement text
1fef0 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65   and an estimate
1ff00 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74   of wall-clock t
1ff10 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f  ime.** of how lo
1ff20 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  ng that statemen
1ff30 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20  t took to run.  
1ff40 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
1ff50 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73  lback.** time is
1ff60 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e   in units of nan
1ff70 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65  oseconds, howeve
1ff80 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  r the current im
1ff90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
1ffa0 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20  is only capable 
1ffb0 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72  of millisecond r
1ffc0 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65  esolution so the
1ffd0 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69   six least signi
1ffe0 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73  ficant.** digits
1fff0 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65   in the time are
20000 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46   meaningless.  F
20010 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
20020 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68  f SQLite.** migh
20030 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65  t provide greate
20040 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20  r resolution on 
20050 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c  the profiler cal
20060 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73  lback.  The.** s
20070 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
20080 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e   function is con
20090 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65  sidered experime
200a0 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73  ntal and is.** s
200b0 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
200c0 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
200d0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
200e0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
200f0 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20  trace(sqlite3*, 
20100 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f  void(*xTrace)(vo
20110 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  id*,const char*)
20120 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45  , void*);.SQLITE
20130 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f  _EXPERIMENTAL vo
20140 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
20150 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
20160 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
20170 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
20180 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
20190 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
201a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
201b0 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
201c0 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
201d0 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
201e0 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c  s_handler(D,N,X,
201f0 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  P) interface cau
20200 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ses the callback
20210 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74  .** function X t
20220 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72  o be invoked per
20230 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
20240 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
20250 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
20260 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c  e3_exec()], [sql
20270 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
20280 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
20290 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61  ble()] for.** da
202a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
202b0 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  n D.  An example
202c0 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a   use for this.**
202d0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
202e0 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
202f0 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
20300 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
20310 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50  ^The parameter P
20320 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
20330 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  gh as the only p
20340 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
20350 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
20360 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70  ction X.  ^The p
20370 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68  arameter N is th
20380 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75  e approximate nu
20390 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72  mber of .** [vir
203a0 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73  tual machine ins
203b0 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20  tructions] that 
203c0 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65  are evaluated be
203d0 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65  tween successive
203e0 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
203f0 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  of the callback 
20400 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73  X.  ^If N is les
20410 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20  s than one then 
20420 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20  the progress.** 
20430 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62  handler is disab
20440 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  led..**.** ^Only
20450 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65   a single progre
20460 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62  ss handler may b
20470 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65  e defined at one
20480 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61   time per.** [da
20490 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
204a0 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65  n]; setting a ne
204b0 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  w progress handl
204c0 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a  er cancels the.*
204d0 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74  * old one.  ^Set
204e0 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58  ting parameter X
204f0 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65   to NULL disable
20500 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  s the progress h
20510 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  andler..** ^The 
20520 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
20530 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65   is also disable
20540 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74  d by setting N t
20550 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a  o a value less.*
20560 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20  * than 1..**.** 
20570 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73  ^If the progress
20580 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
20590 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
205a0 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
205b0 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
205c0 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
205d0 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
205e0 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
205f0 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
20600 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
20610 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
20620 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
20630 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
20640 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
20650 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
20660 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
20670 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
20680 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f   invoked the pro
20690 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
206a0 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
206b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
206c0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
206d0 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
206e0 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
206f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20700 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
20710 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
20720 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
20730 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  .**.*/.void sqli
20740 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
20750 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
20760 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  nt, int(*)(void*
20770 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
20780 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
20790 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61  ing A New Databa
207a0 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
207b0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
207c0 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69  nes open an SQLi
207d0 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  te database file
207e0 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79   as specified by
207f0 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d   the .** filenam
20800 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65  e argument. ^The
20810 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
20820 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
20830 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d as UTF-8 for.*
20840 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
20850 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
20860 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54  n_v2() and as UT
20870 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
20880 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72  ve byte.** order
20890 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
208a0 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61  n16(). ^(A [data
208b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
208c0 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c   handle is usual
208d0 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ly.** returned i
208e0 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66  n *ppDb, even if
208f0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
20900 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65  .  The only exce
20910 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a  ption is that.**
20920 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e   if SQLite is un
20930 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
20940 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
20950 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
20960 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20  ject,.** a NULL 
20970 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20  will be written 
20980 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65  into *ppDb inste
20990 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20  ad of a pointer 
209a0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  to the [sqlite3]
209b0 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28  .** object.)^ ^(
209c0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
209d0 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f  is opened (and/o
209e0 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65  r created) succe
209f0 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a  ssfully, then.**
20a00 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
20a10 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
20a20 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
20a30 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
20a40 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c  .)^ ^The.** [sql
20a50 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
20a60 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
20a70 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
20a80 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
20a90 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
20aa0 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
20ab0 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
20ac0 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20  error following 
20ad0 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79  a failure of any
20ae0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
20af0 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e  e3_open() routin
20b00 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  es..**.** ^The d
20b10 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
20b20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f  will be UTF-8 fo
20b30 72 20 64 61 74 61 62 61 73 65 73 20 63 72 65 61  r databases crea
20b40 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c  ted using.** sql
20b50 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
20b60 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
20b70 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  .  ^The default 
20b80 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74  encoding for dat
20b90 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65  abases.** create
20ba0 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f  d using sqlite3_
20bb0 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65  open16() will be
20bc0 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
20bd0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
20be0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20  ..**.** Whether 
20bf0 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
20c00 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
20c10 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
20c20 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ces.** associate
20c30 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
20c40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
20c50 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62   handle should b
20c60 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a  e released by.**
20c70 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
20c80 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
20c90 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c   when it is no l
20ca0 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a  onger required..
20cb0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
20cc0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65  3_open_v2() inte
20cd0 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65  rface works like
20ce0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a   sqlite3_open().
20cf0 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
20d00 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64  t accepts two ad
20d10 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74  ditional paramet
20d20 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ers for addition
20d30 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76  al control.** ov
20d40 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  er the new datab
20d50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
20d60 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72   ^(The flags par
20d70 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c  ameter to.** sql
20d80 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63  ite3_open_v2() c
20d90 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a  an take one of.*
20da0 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
20db0 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70  three values, op
20dc0 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
20dd0 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  d with the .** [
20de0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
20df0 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
20e00 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b  EN_FULLMUTEX], [
20e10 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
20e20 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51  EDCACHE],.** [SQ
20e30 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
20e40 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20  ECACHE], and/or 
20e50 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
20e60 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a  ] flags:)^.**.**
20e70 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b   <dl>.** ^(<dt>[
20e80 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
20e90 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ONLY]</dt>.** <d
20ea0 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
20eb0 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64  s opened in read
20ec0 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20  -only mode.  If 
20ed0 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
20ee0 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79  s not.** already
20ef0 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
20f00 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
20f10 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
20f20 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
20f30 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  ADWRITE]</dt>.**
20f40 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
20f50 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
20f60 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
20f70 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c  ing if possible,
20f80 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f   or reading.** o
20f90 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20  nly if the file 
20fa0 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74  is write protect
20fb0 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74  ed by the operat
20fc0 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20  ing system.  In 
20fd0 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74  either.** case t
20fe0 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74  he database must
20ff0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
21000 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72  otherwise an err
21010 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
21020 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
21030 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
21040 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
21050 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
21060 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
21070 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
21080 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
21090 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e   and writing, an
210a0 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a  d is created if.
210b0 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61  ** it does not a
210c0 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68  lready exist. Th
210d0 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69  is is the behavi
210e0 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79  or that is alway
210f0 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71  s used for.** sq
21100 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
21110 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
21120 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  ).</dd>)^.** </d
21130 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  l>.**.** If the 
21140 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
21150 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
21160 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
21170 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
21180 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
21190 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
211a0 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a  ined with other.
211b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
211c0 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54  READONLY | SQLIT
211d0 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a  E_OPEN_* bits].*
211e0 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
211f0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
21200 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
21210 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
21220 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
21230 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  t, then the data
21240 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
21250 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20  ** opens in the 
21260 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  multi-thread [th
21270 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73  reading mode] as
21280 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e   long as the sin
21290 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f  gle-thread.** mo
212a0 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  de has not been 
212b0 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
212c0 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
212d0 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  e.  ^If the.** [
212e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
212f0 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
21300 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
21310 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
21320 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
21330 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
21340 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
21350 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
21360 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
21370 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
21380 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
21390 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54  tart-time..** ^T
213a0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
213b0 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61  SHAREDCACHE] fla
213c0 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
213d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
213e0 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62   to be.** eligib
213f0 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65  le to use [share
21400 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72  d cache mode], r
21410 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
21420 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
21430 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
21440 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71  nabled using [sq
21450 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
21460 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e  red_cache()].  ^
21470 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  The.** [SQLITE_O
21480 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
21490 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
214a0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
214b0 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20  ction to not.** 
214c0 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b  participate in [
214d0 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
214e0 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  e] even if it is
214f0 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
21500 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
21510 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
21520 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68  _open_v2() is th
21530 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
21540 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
21550 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
21560 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
21570 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
21580 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65  e that.** the ne
21590 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
215a0 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ction should use
215b0 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  .  ^If the fourt
215c0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
215d0 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
215e0 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
215f0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
21600 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a  object is used..
21610 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
21620 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
21630 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69  ry:", then a pri
21640 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20  vate, temporary 
21650 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
21660 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64  se.** is created
21670 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
21680 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d  ion.  ^This in-m
21690 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77  emory database w
216a0 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a  ill vanish when.
216b0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
216c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
216d0 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65  osed.  Future ve
216e0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
216f0 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75   might.** make u
21700 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c  se of additional
21710 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d   special filenam
21720 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  es that begin wi
21730 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61  th the ":" chara
21740 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72  cter..** It is r
21750 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
21760 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
21770 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c  filename actuall
21780 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74  y does begin wit
21790 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61  h.** a ":" chara
217a0 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20  cter you should 
217b0 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e  prefix the filen
217c0 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e  ame with a pathn
217d0 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22  ame such as.** "
217e0 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62  ./" to avoid amb
217f0 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iguity..**.** ^I
21800 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
21810 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  s an empty strin
21820 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  g, then a privat
21830 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20  e, temporary.** 
21840 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65  on-disk database
21850 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64   will be created
21860 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65  .  ^This private
21870 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
21880 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  e.** automatical
21890 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f  ly deleted as so
218a0 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61  on as the databa
218b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
218c0 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b   closed..**.** [
218d0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69  [URI filenames i
218e0 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  n sqlite3_open()
218f0 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e  ]] <h3>URI Filen
21900 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ames</h3>.**.** 
21910 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ^If [URI filenam
21920 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  e] interpretatio
21930 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e  n is enabled, an
21940 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  d the filename a
21950 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e  rgument.** begin
21960 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20  s with "file:", 
21970 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d  then the filenam
21980 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  e is interpreted
21990 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a   as a URI. ^URI.
219a0 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  ** filename inte
219b0 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
219c0 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51  abled if the [SQ
219d0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
219e0 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e  lag is.** set in
219f0 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
21a00 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
21a10 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66  open_v2(), or if
21a20 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20   it has.** been 
21a30 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79  enabled globally
21a40 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
21a50 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f  TE_CONFIG_URI] o
21a60 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a  ption with the.*
21a70 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
21a80 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62  g()] method or b
21a90 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  y the [SQLITE_US
21aa0 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74  E_URI] compile-t
21ab0 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41  ime option..** A
21ac0 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
21ad0 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66  ion 3.7.7, URI f
21ae0 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
21af0 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  tation is turned
21b00 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75   off.** by defau
21b10 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72  lt, but future r
21b20 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
21b30 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55  e might enable U
21b40 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69  RI filename.** i
21b50 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79  nterpretation by
21b60 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22   default.  See "
21b70 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22  [URI filenames]"
21b80 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
21b90 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
21ba0 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61  **.** URI filena
21bb0 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61  mes are parsed a
21bc0 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20  ccording to RFC 
21bd0 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52  3986. ^If the UR
21be0 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a  I contains an.**
21bf0 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e   authority, then
21c00 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68   it must be eith
21c10 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  er an empty stri
21c20 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67  ng or the string
21c30 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22   .** "localhost"
21c40 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72  . ^If the author
21c50 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d  ity is not an em
21c60 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c  pty string or "l
21c70 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a  ocalhost", an .*
21c80 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  * error is retur
21c90 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65  ned to the calle
21ca0 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74  r. ^The fragment
21cb0 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
21cc0 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73  URI, if .** pres
21cd0 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e  ent, is ignored.
21ce0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
21cf0 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d  ses the path com
21d00 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52  ponent of the UR
21d10 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  I as the name of
21d20 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a   the disk file.*
21d30 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73  * which contains
21d40 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e   the database. ^
21d50 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69  If the path begi
21d60 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68  ns with a '/' ch
21d70 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65  aracter, .** the
21d80 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65  n it is interpre
21d90 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75  ted as an absolu
21da0 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65  te path. ^If the
21db0 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62   path does not b
21dc0 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20  egin .** with a 
21dd0 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61  '/' (meaning tha
21de0 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  t the authority 
21df0 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74  section is omitt
21e00 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29  ed from the URI)
21e10 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74  .** then the pat
21e20 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
21e30 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70   as a relative p
21e40 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69  ath. .** ^(On wi
21e50 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74  ndows, the first
21e60 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e   component of an
21e70 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a   absolute path .
21e80 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70  ** is a drive sp
21e90 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67  ecification (e.g
21ea0 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a  . "C:").)^.**.**
21eb0 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72   [[core URI quer
21ec0 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a  y parameters]].*
21ed0 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70  * The query comp
21ee0 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d  onent of a URI m
21ef0 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d  ay contain param
21f00 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69  eters that are i
21f10 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69  nterpreted.** ei
21f20 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69  ther by SQLite i
21f30 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b  tself, or by a [
21f40 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53  VFS | custom VFS
21f50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d   implementation]
21f60 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20  ..** SQLite and 
21f70 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46  its built-in [VF
21f80 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74  Ses] interpret t
21f90 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  he.** following 
21fa0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
21fb0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
21fc0 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62    <li> <b>vfs</b
21fd0 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61  >: ^The "vfs" pa
21fe0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75  rameter may be u
21ff0 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74  sed to specify t
22000 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20  he name of.**   
22010 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74    a VFS object t
22020 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65  hat provides the
22030 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
22040 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
22050 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62   should.**     b
22060 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73  e used to access
22070 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
22080 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20  le on disk. ^If 
22090 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73  this option is s
220a0 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20  et to.**     an 
220b0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65  empty string the
220c0 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a   default VFS obj
220d0 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70  ect is used. ^Sp
220e0 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
220f0 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69  own.**     VFS i
22100 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20  s an error. ^If 
22110 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
22120 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68  ) is used and th
22130 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a  e vfs option is.
22140 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20  **     present, 
22150 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65  then the VFS spe
22160 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70  cified by the op
22170 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65  tion takes prece
22180 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20  dence over.**   
22190 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73    the value pass
221a0 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68  ed as the fourth
221b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
221c0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
221d0 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
221e0 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65  >mode</b>: ^(The
221f0 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
22200 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
22210 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c  ther "ro", "rw",
22220 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f  .**     "rwc", o
22230 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65  r "memory". Atte
22240 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74  mpting to set it
22250 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61   to any other va
22260 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e  lue is.**     an
22270 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20   error)^. .**   
22280 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70    ^If "ro" is sp
22290 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68  ecified, then th
222a0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
222b0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e  ened for read-on
222c0 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  ly .**     acces
222d0 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68  s, just as if th
222e0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
222f0 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61  EADONLY] flag ha
22300 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68  d been set in th
22310 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20  e .**     third 
22320 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
22330 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
22340 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
22350 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a  on is set to .**
22360 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20       "rw", then 
22370 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
22380 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
22390 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63  write (but not c
223a0 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61  reate) .**     a
223b0 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c  ccess, as if SQL
223c0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
223d0 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49  TE (but not SQLI
223e0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20  TE_OPEN_CREATE) 
223f0 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e  had .**     been
22400 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77   set. ^Value "rw
22410 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  c" is equivalent
22420 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68   to setting both
22430 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f   .**     SQLITE_
22440 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61  OPEN_READWRITE a
22450 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  nd SQLITE_OPEN_C
22460 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20  REATE.  ^If the 
22470 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  mode option is.*
22480 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65  *     set to "me
22490 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72  mory" then a pur
224a0 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  e [in-memory dat
224b0 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65  abase] that neve
224c0 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f  r reads.**     o
224d0 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69  r writes from di
224e0 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20  sk is used. ^It 
224f0 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73  is an error to s
22500 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66  pecify a value f
22510 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f  or.**     the mo
22520 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  de parameter tha
22530 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69  t is less restri
22540 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20  ctive than that 
22550 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
22560 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61      the flags pa
22570 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72  ssed in the thir
22580 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
22590 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
225a0 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
225b0 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68  b>cache</b>: ^Th
225c0 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
225d0 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
225e0 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20  either "shared" 
225f0 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61  or.**     "priva
22600 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74  te". ^Setting it
22610 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20   to "shared" is 
22620 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
22630 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20  tting the.**    
22640 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
22650 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20  REDCACHE bit in 
22660 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
22670 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  nt passed to.** 
22680 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e      sqlite3_open
22690 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20  _v2(). ^Setting 
226a0 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  the cache parame
226b0 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22  ter to "private"
226c0 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69   is .**     equi
226d0 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
226e0 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  g the SQLITE_OPE
226f0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62  N_PRIVATECACHE b
22700 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73  it..**     ^If s
22710 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
22720 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
22730 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74   "cache" paramet
22740 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e  er is present in
22750 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69  .**     a URI fi
22760 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75  lename, its valu
22770 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20  e overrides any 
22780 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74  behavior request
22790 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a  ed by setting.**
227a0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
227b0 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72  _PRIVATECACHE or
227c0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
227d0 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a  REDCACHE flag..*
227e0 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73  *.**  <li> <b>ps
227f0 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f  ow</b>: ^The pso
22800 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69  w parameter indi
22810 63 61 74 65 73 20 77 68 65 74 68 65 72 20 6f 72  cates whether or
22820 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20   not the.**     
22830 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77  [powersafe overw
22840 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64  rite] property d
22850 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20  oes or does not 
22860 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20  apply to the.** 
22870 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69      storage medi
22880 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64  a on which the d
22890 61 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73  atabase file res
228a0 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69  ides..**.**  <li
228b0 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a  > <b>nolock</b>:
228c0 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72   ^The nolock par
228d0 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c  ameter is a bool
228e0 65 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65  ean query parame
228f0 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68  ter.**     which
22900 20 69 66 20 73 65 74 20 64 69 73 61 62 6c 65 73   if set disables
22910 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e   file locking in
22920 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61   rollback journa
22930 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a  l modes.  This.*
22940 2a 20 20 20 20 20 69 73 20 75 73 65 66 75 6c 20  *     is useful 
22950 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61 20  for accessing a 
22960 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69  database on a fi
22970 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f  lesystem that do
22980 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75  es not.**     su
22990 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20  pport locking.  
229a0 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61  Caution:  Databa
229b0 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69  se corruption mi
229c0 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 74 77  ght result if tw
229d0 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65  o.**     or more
229e0 20 70 72 6f 63 65 73 73 65 73 20 77 72 69 74 65   processes write
229f0 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
22a00 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e  abase and any on
22a10 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20  e of those.**   
22a20 20 20 70 72 6f 63 65 73 73 65 73 20 75 73 65 73    processes uses
22a30 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a   nolock=1..**.**
22a40 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61    <li> <b>immuta
22a50 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d  ble</b>: ^The im
22a60 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65  mutable paramete
22a70 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71  r is a boolean q
22a80 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61  uery.**     para
22a90 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64 69 63  meter that indic
22aa0 61 74 65 73 20 74 68 61 74 20 74 68 65 20 64 61  ates that the da
22ab0 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 73  tabase file is s
22ac0 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20  tored on.**     
22ad0 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e  read-only media.
22ae0 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c    ^When immutabl
22af0 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65  e is set, SQLite
22b00 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
22b10 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73  e.**     databas
22b20 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65  e file cannot be
22b30 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62   changed, even b
22b40 79 20 61 20 70 72 6f 63 65 73 73 20 77 69 74 68  y a process with
22b50 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70   higher.**     p
22b60 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f  rivilege, and so
22b70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
22b80 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c   opened read-onl
22b90 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e  y and all lockin
22ba0 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61  g.**     and cha
22bb0 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73  nge detection is
22bc0 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74   disabled.  Caut
22bd0 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65  ion: Setting the
22be0 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20   immutable.**   
22bf0 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20    property on a 
22c00 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68  database file th
22c10 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20  at does in fact 
22c20 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c  change can resul
22c30 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f  t.**     in inco
22c40 72 72 65 63 74 20 71 75 65 72 79 20 72 65 73 75  rrect query resu
22c50 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  lts and/or [SQLI
22c60 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f  TE_CORRUPT] erro
22c70 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61  rs..**     See a
22c80 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43  lso: [SQLITE_IOC
22c90 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a  AP_IMMUTABLE]..*
22ca0 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c  *       .** </ul
22cb0 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79  >.**.** ^Specify
22cc0 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70  ing an unknown p
22cd0 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20  arameter in the 
22ce0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
22cf0 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20  of a URI is not 
22d00 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75  an.** error.  Fu
22d10 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
22d20 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e   SQLite might un
22d30 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f  derstand additio
22d40 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72  nal query.** par
22d50 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b  ameters.  See "[
22d60 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
22d70 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65   with special me
22d80 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d  aning to SQLite]
22d90 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  " for.** additio
22da0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
22db0 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
22dc0 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d  ename examples]]
22dd0 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d   <h3>URI filenam
22de0 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a  e examples</h3>.
22df0 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  **.** <table bor
22e00 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65  der="1" align=ce
22e10 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67  nter cellpadding
22e20 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  =5>.** <tr><th> 
22e30 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74  URI filenames <t
22e40 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74  h> Results.** <t
22e50 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
22e60 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
22e70 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66        Open the f
22e80 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
22e90 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
22ea0 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  ectory..** <tr><
22eb0 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66  td> file:/home/f
22ec0 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a  red/data.db<br>.
22ed0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
22ee0 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  :///home/fred/da
22ef0 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20  ta.db <br> .**  
22f00 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c          file://l
22f10 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72  ocalhost/home/fr
22f20 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
22f30 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
22f40 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62    Open the datab
22f50 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  ase file "/home/
22f60 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a  fred/data.db"..*
22f70 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
22f80 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f  //darkstar/home/
22f90 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64  fred/data.db <td
22fa0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
22fb0 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74  n error. "darkst
22fc0 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63  ar" is not a rec
22fd0 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74  ognized authorit
22fe0 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74  y..** <tr><td st
22ff0 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65  yle="white-space
23000 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20  :nowrap"> .**   
23010 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43         file:///C
23020 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e  :/Documents%20an
23030 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65  d%20Settings/fre
23040 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64  d/Desktop/data.d
23050 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69  b.**     <td> Wi
23060 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e  ndows only: Open
23070 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
23080 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65  db" on fred's de
23090 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a  sktop on drive.*
230a0 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e  *          C:. N
230b0 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30  ote that the %20
230c0 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69   escaping in thi
230d0 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74  s example is not
230e0 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20   strictly .**   
230f0 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79         necessary
23100 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74   - space charact
23110 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  ers can be used 
23120 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20  literally.**    
23130 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c        in URI fil
23140 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c  enames..** <tr><
23150 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
23160 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70  ?mode=ro&cache=p
23170 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20  rivate <td> .** 
23180 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
23190 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
231a0 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
231b0 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f  ctory for read-o
231c0 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20  nly access..**  
231d0 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65          Regardle
231e0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
231f0 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68   not shared-cach
23200 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65  e mode is enable
23210 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  d by.**         
23220 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20   default, use a 
23230 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a  private cache..*
23240 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
23250 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
23260 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66  db?vfs=unix-dotf
23270 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20  ile <td>.**     
23280 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
23290 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
232a0 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65  db". Use the spe
232b0 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64  cial VFS "unix-d
232c0 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20  otfile".**      
232d0 20 20 20 20 74 68 61 74 20 75 73 65 73 20 64 6f      that uses do
232e0 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65  t-files in place
232f0 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f   of posix adviso
23300 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c  ry locking..** <
23310 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
23320 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e  a.db?mode=readon
23330 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  ly <td> .**     
23340 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
23350 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74  readonly" is not
23360 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20   a valid option 
23370 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70  for the "mode" p
23380 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74  arameter..** </t
23390 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49  able>.**.** ^URI
233a0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
233b0 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25  ape sequences (%
233c0 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65  HH) are supporte
233d0 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74  d within the pat
233e0 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63  h and.** query c
233f0 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55  omponents of a U
23400 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61  RI. A hexadecima
23410 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
23420 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a  e consists of a.
23430 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20  ** percent sign 
23440 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64  - "%" - followed
23450 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20   by exactly two 
23460 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69  hexadecimal digi
23470 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e  ts .** specifyin
23480 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65  g an octet value
23490 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61  . ^Before the pa
234a0 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70  th or query comp
234b0 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55  onents of a.** U
234c0 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20  RI filename are 
234d0 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65  interpreted, the
234e0 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73  y are encoded us
234f0 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c  ing UTF-8 and al
23500 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61  l .** hexadecima
23510 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
23520 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  es replaced by a
23530 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e   single byte con
23540 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63  taining the.** c
23550 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74  orresponding oct
23560 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63  et. If this proc
23570 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e  ess generates an
23580 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65   invalid UTF-8 e
23590 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  ncoding,.** the 
235a0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
235b0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  fined..**.** <b>
235c0 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
235d0 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
235e0 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f  encoding used fo
235f0 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  r the filename a
23600 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71  rgument.** of sq
23610 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
23620 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23630 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38  () must be UTF-8
23640 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a  , not whatever.*
23650 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75  * codepage is cu
23660 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e  rrently defined.
23670 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74    Filenames cont
23680 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69  aining internati
23690 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65  onal.** characte
236a0 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  rs must be conve
236b0 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72  rted to UTF-8 pr
236c0 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74  ior to passing t
236d0 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  hem into.** sqli
236e0 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
236f0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
23700 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
23710 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d  o Windows Runtim
23720 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  e users:</b>  Th
23730 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65  e temporary dire
23740 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65  ctory must be se
23750 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61  t.** prior to ca
23760 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70  lling sqlite3_op
23770 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
23780 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65  open_v2().  Othe
23790 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a  rwise, various.*
237a0 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20  * features that 
237b0 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20  require the use 
237c0 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  of temporary fil
237d0 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a  es may fail..**.
237e0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
237f0 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
23800 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tory].*/.int sql
23810 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e  ite3_open(.  con
23820 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
23830 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
23840 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
23850 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
23860 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
23870 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
23880 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
23890 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  t sqlite3_open16
238a0 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
238b0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
238c0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
238d0 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
238e0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
238f0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
23900 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
23910 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
23920 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e  3_open_v2(.  con
23930 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
23940 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
23950 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
23960 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
23970 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f  *ppDb,         /
23980 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
23990 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74   handle */.  int
239a0 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20   flags,         
239b0 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f       /* Flags */
239c0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
239d0 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  Vfs        /* Na
239e0 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65  me of VFS module
239f0 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f   to use */.);../
23a00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
23a10 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72  btain Values For
23a20 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a   URI Parameters.
23a30 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
23a40 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73  utility routines
23a50 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20  , useful to VFS 
23a60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c  implementations,
23a70 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74   that check.** t
23a80 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62  o see if a datab
23a90 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55  ase file was a U
23aa0 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65  RI that containe
23ab0 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65  d a specific que
23ac0 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ry .** parameter
23ad0 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61  , and if so obta
23ae0 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  ins the value of
23af0 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61   that query para
23b00 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  meter..**.** If 
23b10 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73  F is the databas
23b20 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74  e filename point
23b30 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  er passed into t
23b40 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f  he xOpen() metho
23b50 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69  d of .** a VFS i
23b60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
23b70 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72  en the flags par
23b80 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28  ameter to xOpen(
23b90 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a  ) has one or .**
23ba0 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51   more of the [SQ
23bb0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f  LITE_OPEN_URI] o
23bc0 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  r [SQLITE_OPEN_M
23bd0 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74  AIN_DB] bits set
23be0 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65   and.** P is the
23bf0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65   name of the que
23c00 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  ry parameter, th
23c10 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  en.** sqlite3_ur
23c20 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
23c30 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
23c40 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70  ue of the P.** p
23c50 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65  arameter if it e
23c60 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20  xists or a NULL 
23c70 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65  pointer if P doe
23c80 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20  s not appear as 
23c90 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61  a .** query para
23ca0 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20  meter on F.  If 
23cb0 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72  P is a query par
23cc0 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68  ameter of F.** h
23cd0 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76  as no explicit v
23ce0 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  alue, then sqlit
23cf0 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
23d00 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a  (F,P) returns.**
23d10 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
23d20 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a   empty string..*
23d30 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
23d40 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
23d50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75  ,B) routine assu
23d60 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20  mes that P is a 
23d70 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d  boolean.** param
23d80 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
23d90 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c   true (1) or fal
23da0 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67  se (0) according
23db0 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a   to the value.**
23dc0 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69   of P.  The sqli
23dd0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
23de0 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72  F,P,B) routine r
23df0 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
23e00 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  if the.** value 
23e10 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  of query paramet
23e20 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22  er P is one of "
23e30 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72  yes", "true", or
23e40 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20   "on" in any.** 
23e50 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76  case or if the v
23e60 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
23e70 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62   a non-zero numb
23e80 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c  er.  The .** sql
23e90 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
23ea0 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73  (F,P,B) routines
23eb0 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28   returns false (
23ec0 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  0) if the value 
23ed0 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61  of.** query para
23ee0 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f  meter P is one o
23ef0 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c  f "no", "false",
23f00 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79   or "off" in any
23f10 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74   case or.** if t
23f20 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20  he value begins 
23f30 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a  with a numeric z
23f40 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f  ero.  If P is no
23f50 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72  t a query.** par
23f60 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69  ameter on F or i
23f70 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
23f80 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74   is does not mat
23f90 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a  ch any of the.**
23fa0 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c   above, then sql
23fb0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
23fc0 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
23fd0 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  (B!=0)..**.** Th
23fe0 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e  e sqlite3_uri_in
23ff0 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69  t64(F,P,D) routi
24000 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20  ne converts the 
24010 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20  value of P into 
24020 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e  a.** 64-bit sign
24030 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72  ed integer and r
24040 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65  eturns that inte
24050 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64  ger, or D if P d
24060 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74  oes not.** exist
24070 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20  .  If the value 
24080 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e  of P is somethin
24090 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20  g other than an 
240a0 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a  integer, then.**
240b0 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
240c0 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69  d..** .** If F i
240d0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
240e0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
240f0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
24100 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61  ) returns NULL a
24110 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  nd.** sqlite3_ur
24120 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
24130 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20   returns B.  If 
24140 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20  F is not a NULL 
24150 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69  pointer and.** i
24160 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
24170 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70   file pathname p
24180 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69  ointer that SQLi
24190 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  te passed into t
241a0 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20  he xOpen.** VFS 
241b0 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65  method, then the
241c0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69   behavior of thi
241d0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64  s routine is und
241e0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
241f0 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  bly.** undesirab
24200 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  le..*/.const cha
24210 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  r *sqlite3_uri_p
24220 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63  arameter(const c
24230 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20  har *zFilename, 
24240 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72  const char *zPar
24250 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  am);.int sqlite3
24260 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e  _uri_boolean(con
24270 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
24280 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72  const char *zPar
24290 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74  am, int bDefault
242a0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
242b0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
242c0 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  64(const char*, 
242d0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c  const char*, sql
242e0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f  ite3_int64);.../
242f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
24300 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d  rror Codes And M
24310 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  essages.**.** ^T
24320 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  he sqlite3_errco
24330 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  de() interface r
24340 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
24350 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  ic [result code]
24360 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
24370 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f   result code] fo
24380 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  r the most recen
24390 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33  t failed sqlite3
243a0 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61  _* API call.** a
243b0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
243c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
243d0 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69  ction]. If a pri
243e0 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c  or API call fail
243f0 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f  ed.** but the mo
24400 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61  st recent API ca
24410 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68  ll succeeded, th
24420 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
24430 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  rom.** sqlite3_e
24440 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65  rrcode() is unde
24450 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  fined.  ^The sql
24460 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
24470 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72  rcode().** inter
24480 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65  face is the same
24490 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
244a0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74  always returns t
244b0 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  he .** [extended
244c0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76   result code] ev
244d0 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64  en when extended
244e0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
244f0 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a  e.** disabled..*
24500 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
24510 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73  3_errmsg() and s
24520 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
24530 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68  ) return English
24540 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78  -language.** tex
24550 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  t that describes
24560 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65   the error, as e
24570 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
24580 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65  TF-16 respective
24590 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20  ly..** ^(Memory 
245a0 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
245b0 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
245c0 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
245d0 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61  rnally..** The a
245e0 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20  pplication does 
245f0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72  not need to worr
24600 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20  y about freeing 
24610 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48  the result..** H
24620 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f  owever, the erro
24630 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62  r string might b
24640 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72  e overwritten or
24650 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a   deallocated by.
24660 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ** subsequent ca
24670 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c  lls to other SQL
24680 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75  ite interface fu
24690 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a  nctions.)^.**.**
246a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
246b0 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65  rstr() interface
246c0 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67   returns the Eng
246d0 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65  lish-language te
246e0 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72  xt.** that descr
246f0 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74  ibes the [result
24700 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38   code], as UTF-8
24710 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f  ..** ^(Memory to
24720 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
24730 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
24740 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
24750 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74  ally.** and must
24760 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79   not be freed by
24770 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
24780 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  )^..**.** When t
24790 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
247a0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69  hreading mode] i
247b0 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67  s in use, it mig
247c0 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73  ht be the.** cas
247d0 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20  e that a second 
247e0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20  error occurs on 
247f0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
24800 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  d in between.** 
24810 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20  the time of the 
24820 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20  first error and 
24830 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73  the call to thes
24840 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  e interfaces..**
24850 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65   When that happe
24860 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ns, the second e
24870 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70  rror will be rep
24880 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73  orted since thes
24890 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
248a0 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68  always report th
248b0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65  e most recent re
248c0 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a  sult.  To avoid.
248d0 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68  ** this, each th
248e0 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20  read can obtain 
248f0 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66  exclusive use of
24900 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
24910 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
24920 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  by invoking [sql
24930 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
24940 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
24950 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20  tex](D)) before 
24960 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20  beginning.** to 
24970 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69  use D and invoki
24980 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
24990 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65  x_leave]([sqlite
249a0 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
249b0 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c  after.** all cal
249c0 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66  ls to the interf
249d0 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65  aces listed here
249e0 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a   are completed..
249f0 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  **.** If an inte
24a00 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
24a10 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20   SQLITE_MISUSE, 
24a20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69  that means the i
24a30 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20  nterface.** was 
24a40 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63  invoked incorrec
24a50 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69  tly by the appli
24a60 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74  cation.  In that
24a70 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72   case, the.** er
24a80 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
24a90 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20  sage may or may 
24aa0 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69  not be set..*/.i
24ab0 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  nt sqlite3_errco
24ac0 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
24ad0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
24ae0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71  ended_errcode(sq
24af0 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73  lite3 *db);.cons
24b00 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
24b10 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29  errmsg(sqlite3*)
24b20 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
24b30 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
24b40 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20  qlite3*);.const 
24b50 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
24b60 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  rstr(int);../*.*
24b70 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
24b80 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
24b90 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
24ba0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24bb0 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  t} {prepared sta
24bc0 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41  tements}.**.** A
24bd0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
24be0 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
24bf0 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51  ents a single SQ
24c00 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  L statement..** 
24c10 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76  This object is v
24c20 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61  ariously known a
24c30 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74  s a "prepared st
24c40 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a  atement" or a.**
24c50 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73   "compiled SQL s
24c60 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d  tatement" or sim
24c70 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d  ply as a "statem
24c80 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent"..**.** The 
24c90 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d  life of a statem
24ca0 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20  ent object goes 
24cb0 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74  something like t
24cc0 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  his:.**.** <ol>.
24cd0 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74  ** <li> Create t
24ce0 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
24cf0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
24d00 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61  _v2()] or a rela
24d10 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63  ted.**      func
24d20 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69  tion..** <li> Bi
24d30 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f  nd values to [ho
24d40 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75  st parameters] u
24d50 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
24d60 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20  _bind_*().**    
24d70 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a    interfaces..**
24d80 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51   <li> Run the SQ
24d90 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  L by calling [sq
24da0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e  lite3_step()] on
24db0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
24dc0 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74  .** <li> Reset t
24dd0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  he statement usi
24de0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
24df0 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63  t()] then go bac
24e00 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65  k.**      to ste
24e10 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65  p 2.  Do this ze
24e20 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ro or more times
24e30 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f  ..** <li> Destro
24e40 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  y the object usi
24e50 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
24e60 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c  lize()]..** </ol
24e70 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f  >.**.** Refer to
24e80 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f   documentation o
24e90 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74  n individual met
24ea0 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61  hods above for a
24eb0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
24ec0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  ormation..*/.typ
24ed0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
24ee0 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
24ef0 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _stmt;../*.** CA
24f00 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65  PI3REF: Run-time
24f10 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28   Limits.**.** ^(
24f20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
24f30 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f  llows the size o
24f40 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72  f various constr
24f50 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74  ucts to be limit
24f60 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65  ed.** on a conne
24f70 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74  ction by connect
24f80 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20  ion basis.  The 
24f90 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
24fa0 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  is the.** [datab
24fb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
24fc0 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74  whose limit is t
24fd0 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72  o be set or quer
24fe0 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ied.  The.** sec
24ff0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
25000 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d   one of the [lim
25010 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74  it categories] t
25020 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20  hat define a.** 
25030 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75  class of constru
25040 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c  cts to be size l
25050 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69  imited.  The thi
25060 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
25070 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74  the.** new limit
25080 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72   for that constr
25090 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66  uct.)^.**.** ^If
250a0 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69   the new limit i
250b0 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  s a negative num
250c0 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69  ber, the limit i
250d0 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  s unchanged..** 
250e0 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74  ^(For each limit
250f0 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45   category SQLITE
25100 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f  _LIMIT_<i>NAME</
25110 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a  i> there is a .*
25120 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64  * [limits | hard
25130 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a   upper bound].**
25140 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
25150 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70  time by a C prep
25160 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63  rocessor macro c
25170 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73  alled.** [limits
25180 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69   | SQLITE_MAX_<i
25190 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28  >NAME</i>]..** (
251a0 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e  The "_LIMIT_" in
251b0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61   the name is cha
251c0 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e  nged to "_MAX_".
251d0 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73  ))^.** ^Attempts
251e0 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c   to increase a l
251f0 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68  imit above its h
25200 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20  ard upper bound 
25210 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20  are.** silently 
25220 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65  truncated to the
25230 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
25240 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64  d..**.** ^Regard
25250 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
25260 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74  or not the limit
25270 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68   was changed, th
25280 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  e .** [sqlite3_l
25290 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63  imit()] interfac
252a0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72  e returns the pr
252b0 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65  ior value of the
252c0 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63   limit..** ^Henc
252d0 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63  e, to find the c
252e0 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20  urrent value of 
252f0 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20  a limit without 
25300 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20  changing it,.** 
25310 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68  simply invoke th
25320 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74  is interface wit
25330 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  h the third para
25340 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e  meter set to -1.
25350 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20  .**.** Run-time 
25360 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e  limits are inten
25370 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61  ded for use in a
25380 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
25390 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20   manage.** both 
253a0 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e  their own intern
253b0 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  al database and 
253c0 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74  also databases t
253d0 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c  hat are controll
253e0 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74  ed.** by untrust
253f0 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  ed external sour
25400 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ces.  An example
25410 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67   application mig
25420 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62  ht be a.** web b
25430 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20  rowser that has 
25440 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65  its own database
25450 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69  s for storing hi
25460 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70  story and.** sep
25470 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20  arate databases 
25480 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61  controlled by Ja
25490 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61  vaScript applica
254a0 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64  tions downloaded
254b0 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65  .** off the Inte
254c0 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72  rnet.  The inter
254d0 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61  nal databases ca
254e0 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a  n be given the.*
254f0 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74  * large, default
25500 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61   limits.  Databa
25510 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65  ses managed by e
25520 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20  xternal sources 
25530 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20  can.** be given 
25540 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d  much smaller lim
25550 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20  its designed to 
25560 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c  prevent a denial
25570 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61   of service.** a
25580 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65  ttack.  Develope
25590 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61  rs might also wa
255a0 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73  nt to use the [s
255b0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
255c0 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65  rizer()].** inte
255d0 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72  rface to further
255e0 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74   control untrust
255f0 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a  ed SQL.  The siz
25600 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
25610 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  e.** created by 
25620 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72  an untrusted scr
25630 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61  ipt can be conta
25640 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ined using the.*
25650 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  * [max_page_coun
25660 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a  t] [PRAGMA]..**.
25670 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20  ** New run-time 
25680 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
25690 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
256a0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
256b0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
256c0 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c  _limit(sqlite3*,
256d0 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77   int id, int new
256e0 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Val);../*.** CAP
256f0 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
25700 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73  Limit Categories
25710 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c  .** KEYWORDS: {l
25720 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b  imit category} {
25730 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  *limit categorie
25740 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  s}.**.** These c
25750 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
25760 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61  various performa
25770 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68  nce limits.** th
25780 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65  at can be lowere
25790 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73  d at run-time us
257a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
257b0 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79  it()]..** The sy
257c0 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65  nopsis of the me
257d0 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61  anings of the va
257e0 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20  rious limits is 
257f0 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20  shown below..** 
25800 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  Additional infor
25810 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  mation is availa
25820 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c  ble at [limits |
25830 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74   Limits in SQLit
25840 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  e]..**.** <dl>.*
25850 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
25860 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
25870 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
25880 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
25890 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
258a0 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
258b0 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
258c0 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64  row, in bytes.<d
258d0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
258e0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
258f0 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
25900 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
25910 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
25920 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
25930 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
25940 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65  atement, in byte
25950 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
25960 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
25970 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51  OLUMN]] ^(<dt>SQ
25980 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
25990 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  N</dt>.** <dd>Th
259a0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
259b0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
259c0 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f   table definitio
259d0 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72  n or in the.** r
259e0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
259f0 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d  SELECT] or the m
25a00 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
25a10 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69   columns in an i
25a20 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e  ndex.** or in an
25a30 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f   ORDER BY or GRO
25a40 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64  UP BY clause.</d
25a50 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
25a60 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
25a70 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
25a80 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
25a90 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
25aa0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
25ab0 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20  th of the parse 
25ac0 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72  tree on any expr
25ad0 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  ession.</dd>)^.*
25ae0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
25af0 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
25b00 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ECT]] ^(<dt>SQLI
25b10 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
25b20 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a  D_SELECT</dt>.**
25b30 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
25b40 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
25b50 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
25b60 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
25b70 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
25b80 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
25b90 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  E_OP]] ^(<dt>SQL
25ba0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
25bb0 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
25bc0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
25bd0 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
25be0 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
25bf0 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
25c00 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
25c10 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
25c20 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74  ent.  This limit
25c30 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
25c40 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74  y.** enforced, t
25c50 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74  hough that might
25c60 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d   be added in som
25c70 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
25c80 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f   of.** SQLite.</
25c90 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
25ca0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
25cb0 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e  ION_ARG]] ^(<dt>
25cc0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
25cd0 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a  CTION_ARG</dt>.*
25ce0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
25cf0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  m number of argu
25d00 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74  ments on a funct
25d10 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
25d20 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
25d30 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64  _ATTACHED]] ^(<d
25d40 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
25d50 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
25d60 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
25d70 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43  number of [ATTAC
25d80 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74  H | attached dat
25d90 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a  abases].)^</dd>.
25da0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
25db0 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
25dc0 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28  N_LENGTH]].** ^(
25dd0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
25de0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
25df0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
25e00 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
25e10 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65  gth of the patte
25e20 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rn argument to t
25e30 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20  he [LIKE] or.** 
25e40 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73  [GLOB] operators
25e50 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
25e60 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
25e70 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a  RIABLE_NUMBER]].
25e80 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
25e90 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
25ea0 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  UMBER</dt>.** <d
25eb0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e  d>The maximum in
25ec0 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e  dex number of an
25ed0 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  y [parameter] in
25ee0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
25ef0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  t.)^.**.** [[SQL
25f00 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
25f10 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
25f20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
25f30 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  GGER_DEPTH</dt>.
25f40 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
25f50 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75  um depth of recu
25f60 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65  rsion for trigge
25f70 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
25f80 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
25f90 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d  WORKER_THREADS]]
25fa0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25fb0 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
25fc0 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  DS</dt>.** <dd>T
25fd0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
25fe0 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77  r of auxiliary w
25ff0 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74 68  orker threads th
26000 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b  at a single.** [
26010 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26020 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f  nt] may start.</
26030 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
26040 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
26050 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
26060 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26070 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
26080 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
26090 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
260a0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
260b0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
260c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
260d0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
260e0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
260f0 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
26100 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
26110 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
26120 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
26130 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
26140 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
26150 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
26160 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
26170 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
26180 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
26190 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
261a0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
261b0 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
261c0 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
261d0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
261e0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
261f0 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
26200 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
26210 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
26220 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
26230 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
26240 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20  _TRIGGER_DEPTH  
26250 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65            10.#de
26260 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
26270 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
26280 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f             11../
26290 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
262a0 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
262b0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59  Statement.** KEY
262c0 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74  WORDS: {SQL stat
262d0 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a  ement compiler}.
262e0 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
262f0 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
26300 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
26310 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
26320 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
26330 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
26340 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
26350 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
26360 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
26370 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
26380 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
26390 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
263a0 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
263b0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
263c0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
263d0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
263e0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
263f0 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61  en16()].  The da
26400 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26410 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20  n must not have 
26420 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  been closed..**.
26430 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
26440 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20  gument, "zSql", 
26450 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
26460 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
26470 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
26480 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
26490 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
264a0 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
264b0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
264c0 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66  e_v2().** interf
264d0 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20  aces use UTF-8, 
264e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
264f0 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69  are16() and sqli
26500 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
26510 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36  ().** use UTF-16
26520 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
26530 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
26540 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  s less than zero
26550 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
26560 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  ead up to the.**
26570 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
26580 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74  inator. ^If nByt
26590 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
265a0 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68  e, then it is th
265b0 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d  e maximum.** num
265c0 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65  ber of  bytes re
265d0 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e  ad from zSql.  ^
265e0 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f  When nByte is no
265f0 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a  n-negative, the.
26600 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65  ** zSql string e
26610 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68  nds at either th
26620 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f  e first '\000' o
26630 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61  r '\u0000' chara
26640 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e  cter or.** the n
26650 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68  Byte-th byte, wh
26660 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
26670 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c  rst. If the call
26680 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74  er knows.** that
26690 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74   the supplied st
266a0 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d  ring is nul-term
266b0 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65  inated, then the
266c0 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a  re is a small.**
266d0 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76   performance adv
266e0 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69  antage to be gai
266f0 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61  ned by passing a
26700 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
26710 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75  r that.** is equ
26720 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72  al to the number
26730 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
26740 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69   input string <i
26750 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a  >including</i>.*
26760 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e  * the nul-termin
26770 61 74 6f 72 20 62 79 74 65 73 20 61 73 20 74 68  ator bytes as th
26780 69 73 20 73 61 76 65 73 20 53 51 4c 69 74 65 20  is saves SQLite 
26790 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a  from having to.*
267a0 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66  * make a copy of
267b0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
267c0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54  g..**.** ^If pzT
267d0 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ail is not NULL 
267e0 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20  then *pzTail is 
267f0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
26800 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a   the first byte.
26810 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  ** past the end 
26820 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c  of the first SQL
26830 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
26840 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ql.  These routi
26850 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70  nes only.** comp
26860 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74  ile the first st
26870 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c  atement in zSql,
26880 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c   so *pzTail is l
26890 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a  eft pointing to.
268a0 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20  ** what remains 
268b0 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a  uncompiled..**.*
268c0 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65  * ^*ppStmt is le
268d0 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61  ft pointing to a
268e0 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61   compiled [prepa
268f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
26900 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78  hat can be.** ex
26910 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ecuted using [sq
26920 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20  lite3_step()].  
26930 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20  ^If there is an 
26940 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69  error, *ppStmt i
26950 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  s set.** to NULL
26960 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74  .  ^If the input
26970 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e   text contains n
26980 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e  o SQL (if the in
26990 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a  put is an empty.
269a0 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ** string or a c
269b0 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
269c0 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
269d0 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ULL..** The call
269e0 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73  ing procedure is
269f0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
26a00 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
26a10 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74  mpiled.** SQL st
26a20 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
26a30 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
26a40 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20  )] after it has 
26a50 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
26a60 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20  ..** ppStmt may 
26a70 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  not be NULL..**.
26a80 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20  ** ^On success, 
26a90 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  the sqlite3_prep
26aa0 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20  are() family of 
26ab0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
26ac0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20  [SQLITE_OK];.** 
26ad0 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  otherwise an [er
26ae0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
26af0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
26b00 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
26b10 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65  _v2() and sqlite
26b20 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
26b30 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a   interfaces are.
26b40 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  ** recommended f
26b50 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72  or all new progr
26b60 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64  ams. The two old
26b70 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  er interfaces ar
26b80 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f  e retained.** fo
26b90 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
26ba0 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74  atibility, but t
26bb0 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63  heir use is disc
26bc0 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20  ouraged..** ^In 
26bd0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
26be0 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65  ces, the prepare
26bf0 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  d statement.** t
26c00 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20  hat is returned 
26c10 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
26c20 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74  mt] object) cont
26c30 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  ains a copy of t
26c40 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
26c50 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61  QL text. This ca
26c60 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65  uses the [sqlite
26c70 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66  3_step()] interf
26c80 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65  ace to.** behave
26c90 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20   differently in 
26ca0 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a  three ways:.**.*
26cb0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a  * <ol>.** <li>.*
26cc0 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
26cd0 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
26ce0 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65  s, instead of re
26cf0 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
26d00 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a  SCHEMA] as it.**
26d10 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20   always used to 
26d20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  do, [sqlite3_ste
26d30 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61  p()] will automa
26d40 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
26d50 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61  e the SQL.** sta
26d60 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74  tement and try t
26d70 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20  o run it again. 
26d80 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49  As many as [SQLI
26d90 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45  TE_MAX_SCHEMA_RE
26da0 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20  TRY].** retries 
26db0 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72  will occur befor
26dc0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
26dd0 20 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 65   gives up and re
26de0 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a  turns an error..
26df0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
26e00 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20  li>.** ^When an 
26e10 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73  error occurs, [s
26e20 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
26e30 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  ill return one o
26e40 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a  f the detailed.*
26e50 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  * [error codes] 
26e60 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
26e70 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65  or codes].  ^The
26e80 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
26e90 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71   was that.** [sq
26ea0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
26eb0 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
26ec0 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54  a generic [SQLIT
26ed0 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
26ee0 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20  code.** and the 
26ef0 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c  application woul
26f00 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61  d have to make a
26f10 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20   second call to 
26f20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
26f30 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f  ].** in order to
26f40 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c   find the underl
26f50 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68  ying cause of th
26f60 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20  e problem. With 
26f70 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65  the "v2" prepare
26f80 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20  .** interfaces, 
26f90 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72  the underlying r
26fa0 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72  eason for the er
26fb0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
26fc0 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20  immediately..** 
26fd0 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
26fe0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63  .** ^If the spec
26ff0 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64  ific value bound
27000 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c   to [parameter |
27010 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d   host parameter]
27020 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52   in the .** WHER
27030 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69  E clause might i
27040 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f  nfluence the cho
27050 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
27060 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e  n for a statemen
27070 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73  t,.** then the s
27080 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65  tatement will be
27090 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
270a0 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66  ecompiled, as if
270b0 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20   there had been 
270c0 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61  .** a schema cha
270d0 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73  nge, on the firs
270e0 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  t  [sqlite3_step
270f0 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69  ()] call followi
27100 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a  ng any change.**
27110 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
27120 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e  _bind_text | bin
27130 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b  dings] of that [
27140 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20  parameter]. .** 
27150 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61  ^The specific va
27160 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61  lue of WHERE-cla
27170 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  use [parameter] 
27180 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
27190 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f  the .** choice o
271a0 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20  f query plan if 
271b0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
271c0 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73   the left-hand s
271d0 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a  ide of a [LIKE].
271e0 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65  ** or [GLOB] ope
271f0 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20  rator or if the 
27200 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d  parameter is com
27210 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65  pared to an inde
27220 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e  xed column.** an
27230 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e  d the [SQLITE_EN
27240 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70  ABLE_STAT3] comp
27250 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
27260 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c  is enabled..** <
27270 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f  /li>.** </ol>.*/
27280 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
27290 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20  pare(.  sqlite3 
272a0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
272b0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
272c0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
272d0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
272e0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
272f0 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
27300 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
27310 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
27320 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
27330 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
27340 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
27350 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
27360 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
27370 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
27380 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
27390 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
273a0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
273b0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
273c0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
273d0 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71  prepare_v2(.  sq
273e0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
273f0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
27400 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
27410 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
27420 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
27430 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
27440 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
27450 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
27460 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
27470 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
27480 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
27490 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
274a0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
274b0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
274c0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
274d0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
274e0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
274f0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
27500 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
27510 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
27520 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
27530 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
27540 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
27550 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
27560 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
27570 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
27580 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
27590 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
275a0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
275b0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
275c0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
275d0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
275e0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
275f0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
27600 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
27610 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
27620 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
27630 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
27640 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
27650 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
27660 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69  are16_v2(.  sqli
27670 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
27680 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
27690 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
276a0 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
276b0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
276c0 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
276d0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
276e0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
276f0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
27700 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
27710 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
27720 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
27730 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
27740 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
27750 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
27760 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
27770 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
27780 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
27790 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ql */.);../*.** 
277a0 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65  CAPI3REF: Retrie
277b0 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53  ving Statement S
277c0 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  QL.**.** ^This i
277d0 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
277e0 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65  used to retrieve
277f0 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66   a saved copy of
27800 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a   the original.**
27810 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74   SQL text used t
27820 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70  o create a [prep
27830 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
27840 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  if that statemen
27850 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  t was.** compile
27860 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  d using either [
27870 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
27880 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
27890 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
278a0 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
278b0 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71   *sqlite3_sql(sq
278c0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
278d0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
278e0 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
278f0 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
27900 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61  nt Writes The Da
27910 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68  tabase.**.** ^Th
27920 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
27930 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72  eadonly(X) inter
27940 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
27950 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a  e (non-zero) if.
27960 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  ** and only if t
27970 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
27980 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20  tement] X makes 
27990 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65  no direct change
279a0 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  s to.** the cont
279b0 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
279c0 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20  ase file..**.** 
279d0 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69  Note that [appli
279e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
279f0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72  QL functions] or
27a00 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62  .** [virtual tab
27a10 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67  les] might chang
27a20 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  e the database i
27a30 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73  ndirectly as a s
27a40 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a  ide effect.  .**
27a50 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
27a60 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  if an applicatio
27a70 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63  n defines a func
27a80 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68  tion "eval()" th
27a90 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71  at .** calls [sq
27aa0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74  lite3_exec()], t
27ab0 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  hen the followin
27ac0 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  g SQL statement 
27ad0 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20  would.** change 
27ae0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
27af0 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65  e through side-e
27b00 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ffects:.**.** <b
27b10 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
27b20 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61  **    SELECT eva
27b30 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  l('DELETE FROM t
27b40 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20  1') FROM t2;.** 
27b50 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
27b60 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65  te>.**.** But be
27b70 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43  cause the [SELEC
27b80 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  T] statement doe
27b90 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
27ba0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a   database file.*
27bb0 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69  * directly, sqli
27bc0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
27bd0 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20  y() would still 
27be0 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a  return true.)^.*
27bf0 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f  *.** ^Transactio
27c00 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d  n control statem
27c10 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45  ents such as [BE
27c20 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20  GIN], [COMMIT], 
27c30 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b  [ROLLBACK],.** [
27c40 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20  SAVEPOINT], and 
27c50 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20  [RELEASE] cause 
27c60 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
27c70 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72  donly() to retur
27c80 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65  n true,.** since
27c90 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20   the statements 
27ca0 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f  themselves do no
27cb0 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66  t actually modif
27cc0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62  y the database b
27cd0 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65  ut.** rather the
27ce0 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69  y control the ti
27cf0 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68  ming of when oth
27d00 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f  er statements mo
27d10 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74  dify the .** dat
27d20 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54  abase.  ^The [AT
27d30 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43  TACH] and [DETAC
27d40 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c  H] statements al
27d50 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69  so cause.** sqli
27d60 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
27d70 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72  y() to return tr
27d80 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20  ue since, while 
27d90 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73  those statements
27da0 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63  .** change the c
27db0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20  onfiguration of 
27dc0 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
27dd0 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e  ction, they do n
27de0 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e  ot make .** chan
27df0 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65  ges to the conte
27e00 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
27e10 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b  se files on disk
27e20 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
27e30 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73  _stmt_readonly(s
27e40 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
27e50 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
27e60 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
27e70 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  If A Prepared St
27e80 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e  atement Has Been
27e90 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68   Reset.**.** ^Th
27ea0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  e sqlite3_stmt_b
27eb0 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65  usy(S) interface
27ec0 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e   returns true (n
27ed0 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a  on-zero) if the.
27ee0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
27ef0 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65  tement] S has be
27f00 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65  en stepped at le
27f10 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a  ast once using .
27f20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
27f30 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f 74  (S)] but has not
27f40 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69   run to completi
27f50 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f  on and/or has no
27f60 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74  t .** been reset
27f70 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
27f80 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65  reset(S)].  ^The
27f90 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
27fa0 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61  sy(S).** interfa
27fb0 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  ce returns false
27fc0 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20   if S is a NULL 
27fd0 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69  pointer.  If S i
27fe0 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c  s not a .** NULL
27ff0 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20   pointer and is 
28000 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  not a pointer to
28010 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72   a valid [prepar
28020 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
28030 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68   object, then th
28040 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
28050 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
28060 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65  ably undesirable
28070 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
28080 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
28090 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f  ed in combinatio
280a0 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  n [sqlite3_next_
280b0 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f  stmt()].** to lo
280c0 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65  cate all prepare
280d0 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73  d statements ass
280e0 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64  ociated with a d
280f0 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e  atabase .** conn
28100 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20  ection that are 
28110 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67  in need of being
28120 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61   reset.  This ca
28130 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f  n be used,.** fo
28140 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69  r example, in di
28150 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65  agnostic routine
28160 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20  s to search for 
28170 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61  prepared .** sta
28180 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65  tements that are
28190 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73   holding a trans
281a0 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a  action open..*/.
281b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
281c0 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74  _busy(sqlite3_st
281d0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
281e0 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c  I3REF: Dynamical
281f0 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f  ly Typed Value O
28200 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
28210 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71  S: {protected sq
28220 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e  lite3_value} {un
28230 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
28240 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53  3_value}.**.** S
28250 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
28260 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
28270 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ect to represent
28280 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74   all values.** t
28290 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65  hat can be store
282a0 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20  d in a database 
282b0 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73  table. SQLite us
282c0 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e  es dynamic typin
282d0 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c  g.** for the val
282e0 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20  ues it stores.  
282f0 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69  ^Values stored i
28300 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
28310 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62  objects.** can b
28320 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61  e integers, floa
28330 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
28340 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42  s, strings, BLOB
28350 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  s, or NULL..**.*
28360 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  * An sqlite3_val
28370 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65  ue object may be
28380 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74   either "protect
28390 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63  ed" or "unprotec
283a0 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e  ted"..** Some in
283b0 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
283c0 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
283d0 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68  ite3_value.  Oth
283e0 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  er interfaces.**
283f0 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74   will accept eit
28400 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20  her a protected 
28410 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
28420 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
28430 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66  .** Every interf
28440 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73  ace that accepts
28450 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61   sqlite3_value a
28460 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69  rguments specifi
28470 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72  es.** whether or
28480 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73   not it requires
28490 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
284a0 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  ite3_value..**.*
284b0 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f  * The terms "pro
284c0 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70  tected" and "unp
284d0 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20  rotected" refer 
284e0 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  to whether or no
284f0 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20  t.** a mutex is 
28500 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e  held.  An intern
28510 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  al mutex is held
28520 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64   for a protected
28530 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
28540 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20  e object but no 
28550 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
28560 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
28570 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
28580 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51  e object.  If SQ
28590 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
285a0 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68   to be single-th
285b0 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20  readed.** (with 
285c0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
285d0 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b  FE=0] and with [
285e0 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
285f0 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20  fe()] returning 
28600 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69  0).** or if SQLi
28610 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65  te is run in one
28620 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65   of reduced mute
28630 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c  x modes .** [SQL
28640 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
28650 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c  ETHREAD] or [SQL
28660 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
28670 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20  THREAD].** then 
28680 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74  there is no dist
28690 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
286a0 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
286b0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
286c0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
286d0 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20  ts and they can 
286e0 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61  be used intercha
286f0 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65  ngeably.  Howeve
28700 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75  r,.** for maximu
28710 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69  m code portabili
28720 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ty it is recomme
28730 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
28740 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20  ations.** still 
28750 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
28760 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
28770 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
28780 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
28790 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
287a0 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74  even when not st
287b0 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e  rictly required.
287c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
287d0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
287e0 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65  s that are passe
287f0 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20  d as parameters 
28800 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  into the.** impl
28810 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61  ementation of [a
28820 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
28830 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
28840 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e  ] are protected.
28850 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
28860 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65  _value object re
28870 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
28880 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
28890 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65  ue()] is unprote
288a0 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65  cted..** Unprote
288b0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
288c0 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f  ue objects may o
288d0 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
288e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
288f0 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ult_value()] and
28900 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
28910 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  alue()]..** The 
28920 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
28930 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61  lob | sqlite3_va
28940 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69  lue_type()] fami
28950 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  ly of.** interfa
28960 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74  ces require prot
28970 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
28980 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a  lue objects..*/.
28990 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d  typedef struct M
289a0 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  em sqlite3_value
289b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
289c0 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  F: SQL Function 
289d0 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a  Context Object.*
289e0 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74  *.** The context
289f0 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c   in which an SQL
28a00 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74   function execut
28a10 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  es is stored in 
28a20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  an.** sqlite3_co
28a30 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e  ntext object.  ^
28a40 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
28a50 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
28a60 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77  object.** is alw
28a70 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  ays first parame
28a80 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74  ter to [applicat
28a90 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
28aa0 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  functions]..** T
28ab0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
28ac0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
28ad0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
28ae0 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69  on will pass thi
28af0 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72  s.** pointer thr
28b00 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20  ough into calls 
28b10 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
28b20 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  lt_int | sqlite3
28b30 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b  _result()],.** [
28b40 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
28b50 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73  e_context()], [s
28b60 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
28b70 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
28b80 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
28b90 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  le()], [sqlite3_
28ba0 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a  get_auxdata()],.
28bb0 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74  ** and/or [sqlit
28bc0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
28bd0 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
28be0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ruct sqlite3_con
28bf0 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  text sqlite3_con
28c00 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  text;../*.** CAP
28c10 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56  I3REF: Binding V
28c20 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65  alues To Prepare
28c30 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  d Statements.** 
28c40 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20  KEYWORDS: {host 
28c50 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74  parameter} {host
28c60 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f   parameters} {ho
28c70 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
28c80 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  e}.** KEYWORDS: 
28c90 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20  {SQL parameter} 
28ca0 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d  {SQL parameters}
28cb0 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   {parameter bind
28cc0 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ing}.**.** ^(In 
28cd0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
28ce0 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20  t text input to 
28cf0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28d00 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76  _v2()] and its v
28d10 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65  ariants,.** lite
28d20 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c  rals may be repl
28d30 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d  aced by a [param
28d40 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68  eter] that match
28d50 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77  es one of follow
28d60 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73  ing.** templates
28d70 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
28d80 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20  <li>  ?.** <li> 
28d90 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a   ?NNN.** <li>  :
28da0 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56  VVV.** <li>  @VV
28db0 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a  V.** <li>  $VVV.
28dc0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
28dd0 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20  n the templates 
28de0 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65  above, NNN repre
28df0 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72  sents an integer
28e00 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64   literal,.** and
28e10 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20   VVV represents 
28e20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  an alphanumeric 
28e30 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e  identifier.)^  ^
28e40 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68  The values of th
28e50 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ese.** parameter
28e60 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22  s (also called "
28e70 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
28e80 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61  ames" or "SQL pa
28e90 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61  rameters").** ca
28ea0 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74  n be set using t
28eb0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
28ec0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66  *() routines def
28ed0 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  ined here..**.**
28ee0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
28ef0 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
28f00 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
28f10 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a  tines is always.
28f20 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
28f30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
28f40 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  t] object return
28f50 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69  ed from.** [sqli
28f60 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
28f70 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
28f80 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  s..**.** ^The se
28f90 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
28fa0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
28fb0 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  e SQL parameter 
28fc0 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54  to be set..** ^T
28fd0 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20  he leftmost SQL 
28fe0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
28ff0 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57   index of 1.  ^W
29000 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  hen the same nam
29010 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65  ed.** SQL parame
29020 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65  ter is used more
29030 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f   than once, seco
29040 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
29050 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73  t.** occurrences
29060 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69   have the same i
29070 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73  ndex as the firs
29080 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a  t occurrence..**
29090 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20   ^The index for 
290a0 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73  named parameters
290b0 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75   can be looked u
290c0 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  p using the.** [
290d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
290e0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20  ameter_index()] 
290f0 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20  API if desired. 
29100 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66   ^The index.** f
29110 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65  or "?NNN" parame
29120 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75  ters is the valu
29130 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68  e of NNN..** ^Th
29140 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74  e NNN value must
29150 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e   be between 1 an
29160 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  d the [sqlite3_l
29170 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d  imit()].** param
29180 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d  eter [SQLITE_LIM
29190 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
291a0 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c  ER] (default val
291b0 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20  ue: 999)..**.** 
291c0 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
291d0 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65  ent is the value
291e0 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20   to bind to the 
291f0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
29200 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
29210 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
29220 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20  _bind_text() or 
29230 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
29240 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  t16().** or sqli
29250 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20  te3_bind_blob() 
29260 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
29270 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  r then the fourt
29280 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  h parameter.** i
29290 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68  s ignored and th
292a0 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20  e end result is 
292b0 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69  the same as sqli
292c0 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e  te3_bind_null().
292d0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73  .**.** ^(In thos
292e0 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  e routines that 
292f0 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
29300 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
29310 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
29320 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
29330 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
29340 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
29350 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
29360 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74  number of <u>byt
29370 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61  es</u> in the va
29380 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  lue, not the num
29390 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
293a0 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.)^.** ^If the 
293b0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
293c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
293d0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
293e0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
293f0 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
29400 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68   then the length
29410 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   of the string i
29420 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
29430 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74  of bytes up to t
29440 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
29450 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20  rminator..** If 
29460 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
29470 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
29480 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e  bind_blob() is n
29490 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a  egative, then.**
294a0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
294b0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
294c0 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  f a non-negative
294d0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
294e0 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f  r is provided to
294f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
29500 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  xt().** or sqlit
29510 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
29520 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
29530 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a  _text64() then.*
29540 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72  * that parameter
29550 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74   must be the byt
29560 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72  e offset.** wher
29570 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e  e the NUL termin
29580 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72  ator would occur
29590 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74   assuming the st
295a0 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a  ring were NUL.**
295b0 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66   terminated.  If
295c0 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74   any NUL charact
295d0 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74  ers occur at byt
295e0 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74  e offsets less t
295f0 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75  han .** the valu
29600 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20  e of the fourth 
29610 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74  parameter then t
29620 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
29630 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a  ing value will.*
29640 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64  * contain embedd
29650 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65  ed NULs.  The re
29660 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69  sult of expressi
29670 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74  ons involving st
29680 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d  rings.** with em
29690 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75  bedded NULs is u
296a0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
296b0 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d  ^The fifth argum
296c0 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20  ent to the BLOB 
296d0 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69  and string bindi
296e0 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  ng interfaces.**
296f0 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
29700 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65   used to dispose
29710 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a   of the BLOB or.
29720 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20  ** string after 
29730 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73  SQLite has finis
29740 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54  hed with it.  ^T
29750 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
29760 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69   called.** to di
29770 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
29780 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e  B or string even
29790 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20   if the call to 
297a0 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a  bind API fails..
297b0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
297c0 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
297d0 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  the special valu
297e0 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  e [SQLITE_STATIC
297f0 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61  ], then SQLite a
29800 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
29810 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
29820 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d  s in static, unm
29830 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64  anaged space and
29840 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
29850 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  o be freed..** ^
29860 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
29870 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61  ument has the va
29880 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  lue [SQLITE_TRAN
29890 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20  SIENT], then.** 
298a0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73  SQLite makes its
298b0 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
298c0 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d  y of the data im
298d0 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72  mediately, befor
298e0 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  e.** the sqlite3
298f0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
29900 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  e returns..**.**
29910 20 5e 54 68 65 20 73 69 78 74 68 20 61 72 67 75   ^The sixth argu
29920 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
29930 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75  bind_text64() mu
29940 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20  st be one of.** 
29950 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b  [SQLITE_UTF8], [
29960 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b  SQLITE_UTF16], [
29970 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
29980 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
29990 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69  6LE].** to speci
299a0 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  fy the encoding 
299b0 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e 20 74  of the text in t
299c0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
299d0 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73  er.  If.** the s
299e0 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ixth argument to
299f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
29a00 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e  xt64() is not on
29a10 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f  e of the.** allo
29a20 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e  wed values shown
29a30 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68   above, or if th
29a40 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  e text encoding 
29a50 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20  is different.** 
29a60 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e  from the encodin
29a70 67 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  g specified by t
29a80 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  he sixth paramet
29a90 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  er, then the beh
29aa0 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65  avior.** is unde
29ab0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
29ac0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  e sqlite3_bind_z
29ad0 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e  eroblob() routin
29ae0 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f  e binds a BLOB o
29af0 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a  f length N that.
29b00 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  ** is filled wit
29b10 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65  h zeroes.  ^A ze
29b20 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69  roblob uses a fi
29b30 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  xed amount of me
29b40 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e  mory.** (just an
29b50 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64   integer to hold
29b60 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65   its size) while
29b70 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f   it is being pro
29b80 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62  cessed..** Zerob
29b90 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lobs are intende
29ba0 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c  d to serve as pl
29bb0 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42  aceholders for B
29bc0 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f  LOBs whose.** co
29bd0 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77  ntent is later w
29be0 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20  ritten using.** 
29bf0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
29c00 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c  en | incremental
29c10 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69   BLOB I/O] routi
29c20 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74  nes..** ^A negat
29c30 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ive value for th
29c40 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c  e zeroblob resul
29c50 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e  ts in a zero-len
29c60 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20  gth BLOB..**.** 
29c70 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73  ^If any of the s
29c80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
29c90 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
29ca0 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
29cb0 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74  pointer.** for t
29cc0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
29cd0 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20  tement] or with 
29ce0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
29cf0 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a  ment for which.*
29d00 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
29d10 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c  )] has been call
29d20 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79  ed more recently
29d30 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72   than [sqlite3_r
29d40 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e  eset()],.** then
29d50 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72   the call will r
29d60 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  eturn [SQLITE_MI
29d70 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73  SUSE].  If any s
29d80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a  qlite3_bind_().*
29d90 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73  * routine is pas
29da0 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20  sed a [prepared 
29db0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
29dc0 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
29dd0 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  ed, the.** resul
29de0 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  t is undefined a
29df0 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d  nd probably harm
29e00 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64  ful..**.** ^Bind
29e10 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65  ings are not cle
29e20 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ared by the [sql
29e30 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f  ite3_reset()] ro
29e40 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75  utine..** ^Unbou
29e50 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  nd parameters ar
29e60 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
29e70 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
29e80 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
29e90 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
29ea0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
29eb0 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a  success or an.**
29ec0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
29ed0 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77   anything goes w
29ee0 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54  rong..** ^[SQLIT
29ef0 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20  E_TOOBIG] might 
29f00 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  be returned if t
29f10 68 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72  he size of a str
29f20 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65  ing or BLOB.** e
29f30 78 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d  xceeds limits im
29f40 70 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  posed by [sqlite
29f50 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
29f60 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20  _LIMIT_LENGTH]) 
29f70 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41  or.** [SQLITE_MA
29f80 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b  X_LENGTH]..** ^[
29f90 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73  SQLITE_RANGE] is
29fa0 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
29fb0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e   parameter.** in
29fc0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
29fd0 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e  nge.  ^[SQLITE_N
29fe0 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65  OMEM] is returne
29ff0 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61  d if malloc() fa
2a000 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ils..**.** See a
2a010 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
2a020 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2a030 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nt()],.** [sqlit
2a040 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2a050 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b  r_name()], and [
2a060 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2a070 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
2a080 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2a090 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65  bind_blob(sqlite
2a0a0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2a0b0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e  nst void*, int n
2a0c0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2a0d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2a0e0 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74  ind_blob64(sqlit
2a0f0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2a100 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69  onst void*, sqli
2a110 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20  te3_uint64,.    
2a120 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a130 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64      void(*)(void
2a140 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
2a150 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c  _bind_double(sql
2a160 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2a170 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71   double);.int sq
2a180 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73  lite3_bind_int(s
2a190 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2a1a0 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  t, int);.int sql
2a1b0 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28  ite3_bind_int64(
2a1c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a1d0 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  nt, sqlite3_int6
2a1e0 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  4);.int sqlite3_
2a1f0 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  bind_null(sqlite
2a200 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69  3_stmt*, int);.i
2a210 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2a220 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
2a230 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  t*,int,const cha
2a240 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  r*,int,void(*)(v
2a250 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
2a260 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2a270 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a280 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
2a290 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
2a2a0 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
2a2b0 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 73  e3_bind_text64(s
2a2c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2a2d0 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  t, const char*, 
2a2e0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a  sqlite3_uint64,.
2a2f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a300 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29           void(*)
2a310 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65  (void*), unsigne
2a320 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29  d char encoding)
2a330 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2a340 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  nd_value(sqlite3
2a350 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2a360 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  st sqlite3_value
2a370 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
2a380 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  bind_zeroblob(sq
2a390 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2a3a0 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
2a3b0 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
2a3c0 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74  r Of SQL Paramet
2a3d0 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ers.**.** ^This 
2a3e0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
2a3f0 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
2a400 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
2a410 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
2a420 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2a430 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
2a440 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
2a450 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
2a460 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
2a470 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
2a480 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
2a490 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
2a4a0 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
2a4b0 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
2a4c0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2a4d0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
2a4e0 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
2a4f0 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
2a500 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
2a510 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75  ne actually retu
2a520 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66  rns the index of
2a530 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69   the largest (ri
2a540 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61  ghtmost).** para
2a550 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66  meter. For all f
2a560 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e  orms except ?NNN
2a570 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72  , this will corr
2a580 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a  espond to the.**
2a590 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75   number of uniqu
2a5a0 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49  e parameters.  I
2a5b0 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  f parameters of 
2a5c0 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72  the ?NNN form ar
2a5d0 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65  e used,.** there
2a5e0 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20   may be gaps in 
2a5f0 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a  the list.)^.**.*
2a600 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2a610 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2a620 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
2a630 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2a640 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2a650 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2a660 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2a670 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2a680 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2a690 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2a6a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2a6b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a6c0 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
2a6d0 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a   Parameter.**.**
2a6e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
2a6f0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2a700 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  e(P,N) interface
2a710 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
2a720 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68  name of the N-th
2a730 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
2a740 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
2a750 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
2a760 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74  ** ^(SQL paramet
2a770 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
2a780 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
2a790 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
2a7a0 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
2a7b0 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
2a7c0 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
2a7d0 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
2a7e0 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
2a7f0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
2a800 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
2a810 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
2a820 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
2a830 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
2a840 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
2a850 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e  the name.)^.** ^
2a860 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  Parameters of th
2a870 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f  e form "?" witho
2a880 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69  ut a following i
2a890 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e  nteger have no n
2a8a0 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72  ame.** and are r
2a8b0 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e  eferred to as "n
2a8c0 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f  ameless" or "ano
2a8d0 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
2a8e0 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  s"..**.** ^The f
2a8f0 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
2a900 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
2a910 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
2a920 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75  .** ^If the valu
2a930 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e N is out of ra
2a940 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d  nge or if the N-
2a950 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
2a960 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65  ** nameless, the
2a970 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
2a980 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
2a990 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  ed string is.** 
2a9a0 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20  always in UTF-8 
2a9b0 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
2a9c0 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
2a9d0 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67  eter was.** orig
2a9e0 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
2a9f0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
2aa00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2aa10 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
2aa20 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2aa30 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
2aa40 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
2aa50 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
2aa60 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
2aa70 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2aa80 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
2aa90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2aaa0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2aab0 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  x()]..*/.const c
2aac0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e  har *sqlite3_bin
2aad0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2aae0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2aaf0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2ab00 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
2ab10 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
2ab20 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a   A Given Name.**
2ab30 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
2ab40 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
2ab50 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
2ab60 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a  its name.  ^The.
2ab70 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72  ** index value r
2ab80 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61  eturned is suita
2ab90 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74  ble for use as t
2aba0 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72  he second.** par
2abb0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
2abc0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2abd0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e  ite3_bind()].  ^
2abe0 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74  A zero.** is ret
2abf0 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63  urned if no matc
2ac00 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69  hing parameter i
2ac10 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70  s found.  ^The p
2ac20 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
2ac30 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
2ac40 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
2ac50 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
2ac60 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
2ac70 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
2ac80 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
2ac90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2aca0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
2acb0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2acc0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
2acd0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
2ace0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2acf0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
2ad00 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2ad10 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2ad20 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
2ad30 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
2ad40 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71  rameter_index(sq
2ad50 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e  lite3_stmt*, con
2ad60 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
2ad70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ad80 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64  : Reset All Bind
2ad90 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72  ings On A Prepar
2ada0 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed Statement.**.
2adb0 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20  ** ^Contrary to 
2adc0 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
2add0 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
2ade0 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
2adf0 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b  t reset.** the [
2ae00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2ae10 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
2ae20 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2ae30 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65  tement]..** ^Use
2ae40 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
2ae50 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20   reset all host 
2ae60 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55  parameters to NU
2ae70 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  LL..*/.int sqlit
2ae80 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
2ae90 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  s(sqlite3_stmt*)
2aea0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2aeb0 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c  F: Number Of Col
2aec0 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74  umns In A Result
2aed0 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75   Set.**.** ^Retu
2aee0 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
2aef0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
2af00 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
2af10 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70  ned by the.** [p
2af20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2af30 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  t]. ^This routin
2af40 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70  e returns 0 if p
2af50 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a  Stmt is an SQL.*
2af60 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  * statement that
2af70 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e   does not return
2af80 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70   data (for examp
2af90 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e  le an [UPDATE]).
2afa0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2afb0 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
2afc0 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73  ount()].*/.int s
2afd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2afe0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
2aff0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2b000 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d   CAPI3REF: Colum
2b010 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73  n Names In A Res
2b020 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  ult Set.**.** ^T
2b030 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
2b040 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73  turn the name as
2b050 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74  signed to a part
2b060 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  icular column.**
2b070 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
2b080 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
2b090 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68   statement.  ^Th
2b0a0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2b0b0 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72  _name().** inter
2b0c0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2b0d0 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
2b0e0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
2b0f0 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20  8 string.** and 
2b100 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2b110 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20  ame16() returns 
2b120 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
2b130 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
2b140 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  * UTF-16 string.
2b150 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72    ^The first par
2b160 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70  ameter is the [p
2b170 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b180 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65  t].** that imple
2b190 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43  ments the [SELEC
2b1a0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54  T] statement. ^T
2b1b0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2b1c0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  ter is the.** co
2b1d0 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54  lumn number.  ^T
2b1e0 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
2b1f0 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a  mn is number 0..
2b200 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  **.** ^The retur
2b210 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ned string point
2b220 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  er is valid unti
2b230 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72  l either the [pr
2b240 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b250 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65  ].** is destroye
2b260 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69  d by [sqlite3_fi
2b270 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
2b280 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
2b290 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
2b2a0 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
2b2b0 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
2b2c0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2b2d0 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
2b2e0 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
2b2f0 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
2b300 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
2b310 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
2b320 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2b330 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74  mn_name16() on t
2b340 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
2b350 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  **.** ^If sqlite
2b360 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
2b370 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
2b380 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
2b390 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
2b3a0 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
2b3b0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
2b3c0 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
2b3d0 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
2b3e0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
2b3f0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
2b400 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
2b410 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
2b420 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
2b430 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
2b440 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
2b450 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
2b460 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
2b470 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
2b480 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
2b490 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
2b4a0 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
2b4b0 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
2b4c0 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
2b4d0 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
2b4e0 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e  the next..*/.con
2b4f0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2b500 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
2b510 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2b520 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  N);.const void *
2b530 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2b540 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2b550 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
2b560 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
2b570 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
2b580 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
2b590 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2b5a0 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
2b5b0 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
2b5c0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20  e the database, 
2b5d0 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61  table, and.** ta
2b5e0 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
2b5f0 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66  is the origin of
2b600 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
2b610 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a  sult column in.*
2b620 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  * [SELECT] state
2b630 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61  ment..** ^The na
2b640 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
2b650 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
2b660 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
2b670 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
2b680 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
2b690 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
2b6a0 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
2b6b0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
2b6c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
2b6d0 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
2b6e0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2b6f0 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
2b700 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
2b710 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
2b720 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
2b730 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  me..** ^The retu
2b740 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
2b750 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b  alid until the [
2b760 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b770 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
2b780 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
2b790 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2b7a0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
2b7b0 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
2b7c0 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
2b7d0 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
2b7e0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2b7f0 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
2b800 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
2b810 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
2b820 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
2b830 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
2b840 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66   again in a diff
2b850 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a  erent encoding..
2b860 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73  **.** ^The names
2b870 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
2b880 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
2b890 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
2b8a0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
2b8b0 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
2b8c0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  n..**.** ^The fi
2b8d0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
2b8e0 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
2b8f0 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
2b900 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
2b910 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2b920 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
2b930 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68  on about the Nth
2b940 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72   result column r
2b950 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68  eturned by.** th
2b960 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65  e statement, whe
2b970 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
2b980 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
2b990 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65  ment..** ^The le
2b9a0 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  ft-most column i
2b9b0 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74  s column 0 for t
2b9c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
2b9d0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68  *.** ^If the Nth
2b9e0 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
2b9f0 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
2ba00 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  t is an expressi
2ba10 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72  on or.** subquer
2ba20 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63  y and is not a c
2ba30 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65  olumn value, the
2ba40 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66  n all of these f
2ba50 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a  unctions return.
2ba60 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65  ** NULL.  ^These
2ba70 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61   routine might a
2ba80 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  lso return NULL 
2ba90 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
2baa0 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20  cation error.** 
2bab0 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77  occurs.  ^Otherw
2bac0 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
2bad0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2bae0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
2baf0 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72  se, table,.** or
2bb00 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
2bb10 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ry result column
2bb20 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
2bb30 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77  rom..**.** ^As w
2bb40 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
2bb50 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
2bb60 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64   whose names end
2bb70 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
2bb80 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
2bb90 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20  ded strings and 
2bba0 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69  the other functi
2bbb0 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38  ons return UTF-8
2bbc0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41  ..**.** ^These A
2bbd0 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61  PIs are only ava
2bbe0 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
2bbf0 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
2bc00 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
2bc10 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
2bc20 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
2bc30 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
2bc40 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  mbol..**.** If t
2bc50 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
2bc60 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
2bc70 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
2bc80 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
2bc90 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
2bca0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
2bcb0 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
2bcc0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
2bcd0 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
2bce0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2bcf0 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
2bd00 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
2bd10 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71  e or more.** [sq
2bd20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
2bd30 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c  abase_name | col
2bd40 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
2bd50 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20  erfaces].** for 
2bd60 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
2bd70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
2bd80 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
2bd90 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ** at the same t
2bda0 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
2bdb0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2bdc0 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  ed..*/.const cha
2bdd0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2bde0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28  n_database_name(
2bdf0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2be00 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
2be10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2be20 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
2be30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2be40 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
2be50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
2be60 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
2be70 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2be80 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2be90 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
2bea0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2beb0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
2bec0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2bed0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
2bee0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2bef0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
2bf00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
2bf10 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  rigin_name16(sql
2bf20 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2bf30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2bf40 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74  : Declared Datat
2bf50 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52  ype Of A Query R
2bf60 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  esult.**.** ^(Th
2bf70 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2bf80 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
2bf90 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2bfa0 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
2bfb0 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20  t is a [SELECT] 
2bfc0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
2bfd0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
2bfe0 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  the.** returned 
2bff0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
2c000 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61  at [SELECT] is a
2c010 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
2c020 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
2c030 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
2c040 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
2c050 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
2c060 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
2c070 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e  s returned.)^  ^
2c080 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
2c090 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
2c0a0 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70  set is an.** exp
2c0b0 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
2c0c0 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  ery, then a NULL
2c0d0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
2c0e0 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  rned..** ^The re
2c0f0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
2c100 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e   always UTF-8 en
2c110 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  coded..**.** ^(F
2c120 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65  or example, give
2c130 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  n the database s
2c140 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45  chema:.**.** CRE
2c150 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20  ATE TABLE t1(c1 
2c160 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20  VARIANT);.**.** 
2c170 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  and the followin
2c180 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  g statement to b
2c190 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  e compiled:.**.*
2c1a0 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
2c1b0 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
2c1c0 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ** this routine 
2c1d0 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
2c1e0 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
2c1f0 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
2c200 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
2c210 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
2c220 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
2c230 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
2c240 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e  t column (i==0).
2c250 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
2c260 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
2c270 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
2c280 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65  ^So just because
2c290 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20   a column.** is 
2c2a0 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74  declared to cont
2c2b0 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ain a particular
2c2c0 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d   type does not m
2c2d0 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ean that the.** 
2c2e0 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74  data stored in t
2c2f0 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66  hat column is of
2c300 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
2c310 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a  pe.  SQLite is.*
2c320 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64  * strongly typed
2c330 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67  , but the typing
2c340 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20   is dynamic not 
2c350 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a  static.  ^Type.*
2c360 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
2c370 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
2c380 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
2c390 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
2c3a0 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
2c3b0 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f  those values..*/
2c3c0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2c3d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
2c3e0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
2c3f0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
2c400 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2c410 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73  umn_decltype16(s
2c420 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2c430 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c440 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20  EF: Evaluate An 
2c450 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
2c460 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65  .** After a [pre
2c470 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c480 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72   has been prepar
2c490 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a  ed using either.
2c4a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2c4b0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
2c4c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2c4d0 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
2c4e0 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
2c4f0 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
2c500 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
2c510 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2c520 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63  16()], this func
2c530 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20  tion.** must be 
2c540 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
2c550 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
2c560 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  uate the stateme
2c570 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
2c580 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
2c590 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c  avior of the sql
2c5a0 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
2c5b0 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
2c5c0 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
2c5d0 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
2c5e0 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
2c5f0 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72  newer "v2" inter
2c600 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  face.** [sqlite3
2c610 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
2c620 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2c630 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
2c640 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
2c650 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71  ** interface [sq
2c660 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
2c670 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2c680 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
2c690 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
2c6a0 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  ew "v2" interfac
2c6b0 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
2c6c0 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
2c6d0 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
2c6e0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2c6f0 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
2c700 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
2c710 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c  .**.** ^In the l
2c720 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
2c730 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2c740 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72  e will be either
2c750 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a   [SQLITE_BUSY],.
2c760 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
2c770 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
2c780 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
2c790 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
2c7a0 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  E]..** ^With the
2c7b0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
2c7c0 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65   any of the othe
2c7d0 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  r [result codes]
2c7e0 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
2c7f0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d   result codes] m
2c800 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
2c810 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20   as well..**.** 
2c820 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d  ^[SQLITE_BUSY] m
2c830 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61  eans that the da
2c840 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61  tabase engine wa
2c850 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75  s unable to acqu
2c860 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ire the.** datab
2c870 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65  ase locks it nee
2c880 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62  ds to do its job
2c890 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65  .  ^If the state
2c8a0 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49  ment is a [COMMI
2c8b0 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20  T].** or occurs 
2c8c0 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78  outside of an ex
2c8d0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
2c8e0 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e  on, then you can
2c8f0 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74   retry the.** st
2c900 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65  atement.  If the
2c910 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
2c920 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64  t a [COMMIT] and
2c930 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
2c940 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72  n.** explicit tr
2c950 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79  ansaction then y
2c960 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61  ou should rollba
2c970 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
2c980 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e  on before.** con
2c990 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  tinuing..**.** ^
2c9a0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
2c9b0 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
2c9c0 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
2c9d0 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
2c9e0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
2c9f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
2ca00 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
2ca10 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
2ca20 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
2ca30 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
2ca40 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
2ca50 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
2ca60 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
2ca70 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
2ca80 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
2ca90 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49   state..**.** ^I
2caa0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
2cab0 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
2cac0 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
2cad0 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ata, then [SQLIT
2cae0 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74  E_ROW].** is ret
2caf0 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
2cb00 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
2cb10 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70  a is ready for p
2cb20 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
2cb30 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  .** caller. The 
2cb40 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
2cb50 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65  cessed using the
2cb60 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
2cb70 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
2cb80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
2cb90 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
2cba0 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
2cbb0 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
2cbc0 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45  **.** ^[SQLITE_E
2cbd0 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74  RROR] means that
2cbe0 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
2cbf0 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e  r (such as a con
2cc00 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61  straint.** viola
2cc10 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72  tion) has occurr
2cc20 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ed.  sqlite3_ste
2cc30 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
2cc40 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
2cc50 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72  n.** the VM. Mor
2cc60 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61  e information ma
2cc70 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61  y be found by ca
2cc80 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
2cc90 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69  rrmsg()]..** ^Wi
2cca0 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  th the legacy in
2ccb0 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20  terface, a more 
2ccc0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
2ccd0 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ode (for example
2cce0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  ,.** [SQLITE_INT
2ccf0 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45  ERRUPT], [SQLITE
2cd00 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54  _SCHEMA], [SQLIT
2cd10 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20  E_CORRUPT], and 
2cd20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e  so forth).** can
2cd30 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20   be obtained by 
2cd40 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2cd50 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65  _reset()] on the
2cd60 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2cd70 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74  atement].  ^In t
2cd80 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2cd90 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  e,.** the more s
2cda0 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
2cdb0 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64  de is returned d
2cdc0 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74  irectly by sqlit
2cdd0 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a  e3_step()..**.**
2cde0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2cdf0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2ce00 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73  this routine was
2ce10 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70   called inapprop
2ce20 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68  riately..** Perh
2ce30 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65  aps it was calle
2ce40 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  d on a [prepared
2ce50 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2ce60 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20   has.** already 
2ce70 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  been [sqlite3_fi
2ce80 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
2ce90 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68  ed] or on one th
2cea0 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f  at had.** previo
2ceb0 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53  usly returned [S
2cec0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20  QLITE_ERROR] or 
2ced0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
2cee0 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62  Or it could.** b
2cef0 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
2cf00 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
2cf10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2cf20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77  being used by tw
2cf30 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72  o or.** more thr
2cf40 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
2cf50 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e   moment in time.
2cf60 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76  .**.** For all v
2cf70 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
2cf80 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c  e up to and incl
2cf90 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20  uding 3.6.23.1, 
2cfa0 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
2cfb0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
2cfc0 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65  as required afte
2cfd0 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  r sqlite3_step()
2cfe0 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69   returned anythi
2cff0 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e  ng.** other than
2d000 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65   [SQLITE_ROW] be
2d010 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75  fore any subsequ
2d020 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ent invocation o
2d030 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  f.** sqlite3_ste
2d040 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f  p().  Failure to
2d050 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
2d060 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73  red statement us
2d070 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
2d080 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20  _reset()] would 
2d090 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51  result in an [SQ
2d0a0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74  LITE_MISUSE] ret
2d0b0 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  urn from.** sqli
2d0c0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74  te3_step().  But
2d0d0 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33   after version 3
2d0e0 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33  .6.23.1, sqlite3
2d0f0 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a  _step() began.**
2d100 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2d110 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d  3_reset()] autom
2d120 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73  atically in this
2d130 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61   circumstance ra
2d140 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74  ther.** than ret
2d150 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d  urning [SQLITE_M
2d160 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73  ISUSE].  This is
2d170 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20   not considered 
2d180 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a  a compatibility.
2d190 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65  ** break because
2d1a0 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e   any application
2d1b0 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69   that ever recei
2d1c0 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49  ves an SQLITE_MI
2d1d0 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73  SUSE error.** is
2d1e0 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e   broken by defin
2d1f0 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c  ition.  The [SQL
2d200 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53  ITE_OMIT_AUTORES
2d210 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ET] compile-time
2d220 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62   option.** can b
2d230 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72  e used to restor
2d240 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
2d250 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  avior..**.** <b>
2d260 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
2d270 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68  Alert:</b> In th
2d280 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
2d290 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
2d2a0 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c  step().** API al
2d2b0 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
2d2c0 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
2d2d0 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  e, [SQLITE_ERROR
2d2e0 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
2d2f0 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20  .** error other 
2d300 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
2d310 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  Y] and [SQLITE_M
2d320 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
2d330 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
2d340 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
2d350 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2d360 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
2d370 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a  find one of the.
2d380 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  ** specific [err
2d390 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
2d3a0 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
2d3b0 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
2d3c0 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
2d3d0 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
2d3e0 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
2d3f0 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
2d400 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
2d410 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
2d420 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
2d430 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
2d440 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
2d450 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
2d460 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2d470 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2d480 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61  e16_v2()] instea
2d490 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
2d4a0 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
2d4b0 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
2d4c0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2d4d0 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20   interfaces,.** 
2d4e0 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70  then the more sp
2d4f0 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
2d500 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
2d510 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
2d520 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
2d530 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
2d540 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
2d550 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
2d560 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
2d570 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tep(sqlite3_stmt
2d580 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2d590 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63  REF: Number of c
2d5a0 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75  olumns in a resu
2d5b0 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  lt set.**.** ^Th
2d5c0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2d5d0 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63  ount(P) interfac
2d5e0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2d5f0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2d600 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  in the.** curren
2d610 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
2d620 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70  ult set of [prep
2d630 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d640 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72  P..** ^If prepar
2d650 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64  ed statement P d
2d660 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73  oes not have res
2d670 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65  ults ready to re
2d680 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c  turn.** (via cal
2d690 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ls to the [sqlit
2d6a0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20  e3_column_int | 
2d6b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a  sqlite3_column_*
2d6c0 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ()] of.** interf
2d6d0 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74  aces) then sqlit
2d6e0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2d6f0 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e   returns 0..** ^
2d700 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2d710 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
2d720 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30  e also returns 0
2d730 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20   if P is a NULL 
2d740 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65  pointer..** ^The
2d750 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2d760 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72  unt(P) routine r
2d770 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20  eturns 0 if the 
2d780 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
2d790 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2d7a0 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b  p](P) returned [
2d7b0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e  SQLITE_DONE].  ^
2d7c0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2d7d0 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c  _count(P).** wil
2d7e0 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72  l return non-zer
2d7f0 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61  o if previous ca
2d800 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2d810 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
2d820 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  .** [SQLITE_ROW]
2d830 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20  , except in the 
2d840 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41  case of the [PRA
2d850 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f  GMA incremental_
2d860 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65  vacuum].** where
2d870 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
2d880 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61  ns zero since ea
2d890 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20  ch step of that 
2d8a0 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72  multi-step.** pr
2d8b0 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63  agma returns 0 c
2d8c0 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a  olumns of data..
2d8d0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2d8e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2d8f0 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20  count()].*/.int 
2d900 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2d910 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
2d920 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2d930 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d  CAPI3REF: Fundam
2d940 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a  ental Datatypes.
2d950 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
2d960 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e  ITE_TEXT.**.** ^
2d970 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20  (Every value in 
2d980 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f  SQLite has one o
2d990 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74  f five fundament
2d9a0 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a  al datatypes:.**
2d9b0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
2d9c0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
2d9d0 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36  nteger.** <li> 6
2d9e0 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74  4-bit IEEE float
2d9f0 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
2da00 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a  .** <li> string.
2da10 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20  ** <li> BLOB.** 
2da20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75  <li> NULL.** </u
2da30 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  l>)^.**.** These
2da40 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63   constants are c
2da50 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66  odes for each of
2da60 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a   those types..**
2da70 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
2da80 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f  e SQLITE_TEXT co
2da90 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20  nstant was also 
2daa0 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76  used in SQLite v
2dab0 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20  ersion 2.** for 
2dac0 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66  a completely dif
2dad0 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20  ferent meaning. 
2dae0 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c   Software that l
2daf0 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74  inks against bot
2db00 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  h.** SQLite vers
2db10 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65  ion 2 and SQLite
2db20 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c   version 3 shoul
2db30 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45  d use SQLITE3_TE
2db40 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54  XT, not.** SQLIT
2db50 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69  E_TEXT..*/.#defi
2db60 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  ne SQLITE_INTEGE
2db70 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  R  1.#define SQL
2db80 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23  ITE_FLOAT    2.#
2db90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c  define SQLITE_BL
2dba0 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65  OB     4.#define
2dbb0 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20   SQLITE_NULL    
2dbc0 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45   5.#ifdef SQLITE
2dbd0 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51  _TEXT.# undef SQ
2dbe0 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a  LITE_TEXT.#else.
2dbf0 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
2dc00 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69  TEXT     3.#endi
2dc10 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  f.#define SQLITE
2dc20 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a  3_TEXT     3../*
2dc30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2dc40 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d  sult Values From
2dc50 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57   A Query.** KEYW
2dc60 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63  ORDS: {column ac
2dc70 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a  cess functions}.
2dc80 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2dc90 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72  ines form the "r
2dca0 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72  esult set" inter
2dcb0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  face..**.** ^The
2dcc0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
2dcd0 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
2dce0 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f  bout a single co
2dcf0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72  lumn of the curr
2dd00 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  ent.** result ro
2dd10 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e  w of a query.  ^
2dd20 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68  In every case th
2dd30 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2dd40 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   is a pointer.**
2dd50 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
2dd60 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2dd70 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75  t is being evalu
2dd80 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  ated (the [sqlit
2dd90 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61  e3_stmt*].** tha
2dda0 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66  t was returned f
2ddb0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  rom [sqlite3_pre
2ddc0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
2ddd0 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
2dde0 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65  s).** and the se
2ddf0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
2de00 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
2de10 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
2de20 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ch information.*
2de30 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
2de40 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d  rned. ^The leftm
2de50 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
2de60 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73  e result set has
2de70 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a   the index 0..**
2de80 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
2de90 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
2dea0 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74  esult can be det
2deb0 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a  ermined using.**
2dec0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2ded0 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _count()]..**.**
2dee0 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
2def0 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
2df00 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74  urrently point t
2df10 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f  o a valid row, o
2df20 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r if the.** colu
2df30 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  mn index is out 
2df40 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65  of range, the re
2df50 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
2df60 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  d..** These rout
2df70 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
2df80 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
2df90 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2dfa0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2dfb0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
2dfc0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
2dfd0 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
2dfe0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2dff0 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
2e000 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76  _finalize()] hav
2e010 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75  e been called su
2e020 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49  bsequently..** I
2e030 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  f any of these r
2e040 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2e050 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
2e060 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
2e070 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2e080 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b  ze()] or after [
2e090 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2e0a0 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  has returned.** 
2e0b0 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
2e0c0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
2e0d0 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ], the results a
2e0e0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
2e0f0 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   If [sqlite3_ste
2e100 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
2e110 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
2e120 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2e130 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  ].** are called 
2e140 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74  from a different
2e150 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e   thread while an
2e160 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
2e170 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69  nes.** are pendi
2e180 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ng, then the res
2e190 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2e1a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2e1b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2e1c0 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
2e1d0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  urns the.** [SQL
2e1e0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
2e1f0 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
2e200 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
2e210 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
2e220 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
2e230 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76   ^The returned v
2e240 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
2e250 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
2e260 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
2e270 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
2e280 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
2e290 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
2e2a0 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a  L].  The value.*
2e2b0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
2e2c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2e2d0 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
2e2e0 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70  ingful if no typ
2e2f0 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73  e.** conversions
2e300 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61   have occurred a
2e310 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f  s described belo
2e320 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65  w.  After a type
2e330 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20   conversion,.** 
2e340 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
2e350 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2e360 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75  lumn_type() is u
2e370 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72  ndefined.  Futur
2e380 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
2e390 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
2e3a0 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
2e3b0 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
2e3c0 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
2e3d0 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
2e3e0 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  version..**.** ^
2e3f0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2e400 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
2e410 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
2e420 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e430 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69  bytes().** routi
2e440 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
2e450 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2e460 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
2e470 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2e480 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
2e490 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65  F-16 string, the
2e4a0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2e4b0 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74  _bytes() convert
2e4c0 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
2e4d0 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65  to UTF-8 and the
2e4e0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
2e4f0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
2e500 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2e510 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
2e520 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
2e530 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2e540 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
2e550 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
2e560 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
2e570 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
2e580 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2e590 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2e5a0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2e5b0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2e5c0 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
2e5d0 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
2e5e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72  column_bytes() r
2e5f0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
2e600 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2e610 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
2e620 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65  TF-16 string the
2e630 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
2e640 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a  lumn_bytes16().*
2e650 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
2e660 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2e670 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
2e680 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
2e690 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2e6a0 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
2e6b0 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
2e6c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2e6d0 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
2e6e0 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31   string to UTF-1
2e6f0 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  6 and then retur
2e700 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2e710 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
2e720 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
2e730 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
2e740 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2e750 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a  _bytes16() uses.
2e760 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
2e770 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
2e780 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
2e790 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
2e7a0 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
2e7b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2e7c0 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
2e7d0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2e7e0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
2e7f0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2e800 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74  mn_bytes16() ret
2e810 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
2e820 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
2e830 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
2e840 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2e850 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74  ] and .** [sqlit
2e860 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2e870 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c  6()] do not incl
2e880 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
2e890 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20  minators at the 
2e8a0 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
2e8b0 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72  ring.  ^For clar
2e8c0 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20  ity: the values 
2e8d0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
2e8e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e8f0 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c  ytes()] and [sql
2e900 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2e910 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e  s16()] are the n
2e920 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
2e930 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
2e940 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
2e950 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
2e960 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65  *.** ^Strings re
2e970 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2e980 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2e990 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2e9a0 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
2e9b0 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  even empty strin
2e9c0 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
2e9d0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
2e9e0 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20   ^The return.** 
2e9f0 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
2ea00 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2ea10 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67   for a zero-leng
2ea20 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c  th BLOB is a NUL
2ea30 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
2ea40 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74   ^The object ret
2ea50 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
2ea60 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
2ea70 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
2ea80 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2ea90 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
2eaa0 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  An unprotected s
2eab0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2eac0 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  ect.** may only 
2ead0 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71  be used with [sq
2eae0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
2eaf0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2eb00 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
2eb10 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70  ..** If the [unp
2eb20 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2eb30 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72  _value] object r
2eb40 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
2eb50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2eb60 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69  lue()] is used i
2eb70 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c  n any other way,
2eb80 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73   including calls
2eb90 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  .** to routines 
2eba0 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  like [sqlite3_va
2ebb0 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c  lue_int()], [sql
2ebc0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2ebd0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
2ebe0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
2ebf0 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ], then the beha
2ec00 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
2ec10 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  d..**.** These r
2ec20 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20  outines attempt 
2ec30 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
2ec40 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f  alue where appro
2ec50 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a  priate.  ^For.**
2ec60 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
2ec70 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
2ec80 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
2ec90 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
2eca0 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
2ecb0 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
2ecc0 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
2ecd0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
2ece0 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63  perform the.** c
2ecf0 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61  onversion automa
2ed00 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20  tically.  ^(The 
2ed10 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
2ed20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
2ed30 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
2ed40 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
2ed50 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
2ed60 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
2ed70 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
2ed80 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
2ed90 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
2eda0 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
2edb0 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
2edc0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
2edd0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2ede0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
2edf0 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
2ee00 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
2ee10 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
2ee20 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
2ee30 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2ee40 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2ee50 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e  d> Result is a N
2ee60 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
2ee70 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2ee80 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2ee90 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61  <td> Result is a
2eea0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
2eeb0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2eec0 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  R  <td>  FLOAT  
2eed0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
2eee0 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66  rom integer to f
2eef0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
2ef00 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
2ef10 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
2ef20 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
2ef30 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
2ef40 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
2ef50 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2ef60 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e   <td> Same as IN
2ef70 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
2ef80 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2ef90 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2efa0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
2efb0 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
2efc0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
2efd0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2efe0 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
2eff0 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20  of the float.** 
2f000 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2f010 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2f020 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
2f030 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  BLOB.** <tr><td>
2f040 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
2f050 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
2f060 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
2f070 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
2f080 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  T    <td>  FLOAT
2f090 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
2f0a0 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c  to REAL.** <tr><
2f0b0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
2f0c0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
2f0d0 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74   No change.** <t
2f0e0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
2f0f0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2f100 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
2f110 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
2f120 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
2f130 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b   FLOAT    <td> [
2f140 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a  CAST] to REAL.**
2f150 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
2f160 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
2f170 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72    <td> Add a zer
2f180 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20  o terminator if 
2f190 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c  needed.** </tabl
2f1a0 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
2f1b0 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te>)^.**.** The 
2f1c0 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65  table above make
2f1d0 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73  s reference to s
2f1e0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
2f1f0 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69  y functions atoi
2f200 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29  ().** and atof()
2f210 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e  .  SQLite does n
2f220 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68  ot really use th
2f230 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
2f240 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77  It has its.** ow
2f250 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74  n equivalent int
2f260 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20  ernal routines. 
2f270 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20   The atoi() and 
2f280 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65  atof() names are
2f290 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20  .** used in the 
2f2a0 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74  table for brevit
2f2b0 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68  y and because th
2f2c0 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20  ey are familiar 
2f2d0 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f  to most.** C pro
2f2e0 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  grammers..**.** 
2f2f0 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74  Note that when t
2f300 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
2f310 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20  occur, pointers 
2f320 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f  returned by prio
2f330 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  r.** calls to sq
2f340 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2f350 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  b(), sqlite3_col
2f360 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f  umn_text(), and/
2f370 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
2f380 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61  lumn_text16() ma
2f390 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  y be invalidated
2f3a0 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72  ..** Type conver
2f3b0 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65  sions and pointe
2f3c0 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20  r invalidations 
2f3d0 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69  might occur.** i
2f3e0 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
2f3f0 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  cases:.**.** <ul
2f400 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
2f410 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
2f420 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69   a BLOB and sqli
2f430 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2f440 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
2f450 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2f460 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
2f470 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   A zero-terminat
2f480 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20  or might.**     
2f490 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65   need to be adde
2f4a0 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e  d to the string.
2f4b0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
2f4c0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2f4d0 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20  t is UTF-8 text 
2f4e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2f4f0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a  mn_bytes16() or.
2f500 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
2f510 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
2f520 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
2f530 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
2f540 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
2f550 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69    to UTF-16.</li
2f560 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
2f570 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
2f580 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64   UTF-16 text and
2f590 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f5a0 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20  bytes() or.**   
2f5b0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
2f5c0 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c  n_text() is call
2f5d0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
2f5e0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
2f5f0 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
2f600 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  F-8.</li>.** </u
2f610 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72  l>.**.** ^Conver
2f620 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54  sions between UT
2f630 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31  F-16be and UTF-1
2f640 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64  6le are always d
2f650 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64  one in place and
2f660 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c   do.** not inval
2f670 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f  idate a prior po
2f680 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66  inter, though of
2f690 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74   course the cont
2f6a0 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65  ent of the buffe
2f6b0 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72  r.** that the pr
2f6c0 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65  ior pointer refe
2f6d0 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65  rences will have
2f6e0 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20   been modified. 
2f6f0 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20   Other kinds.** 
2f700 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72  of conversion ar
2f710 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  e done in place 
2f720 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69  when it is possi
2f730 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d  ble, but sometim
2f740 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e  es they.** are n
2f750 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
2f760 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
2f770 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
2f780 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
2f790 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20  *.** The safest 
2f7a0 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72  and easiest to r
2f7b0 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69  emember policy i
2f7c0 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73  s to invoke thes
2f7d0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e  e routines.** in
2f7e0 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
2f7f0 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a  owing ways:.**.*
2f800 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  * <ul>.**  <li>s
2f810 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f820 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
2f830 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f840 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
2f850 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
2f860 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
2f870 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
2f880 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
2f890 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
2f8a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2f8b0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
2f8c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f8d0 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
2f8e0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f  </ul>.**.** In o
2f8f0 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20  ther words, you 
2f900 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69  should call sqli
2f910 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2f920 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  ),.** sqlite3_co
2f930 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20  lumn_blob(), or 
2f940 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2f950 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f  ext16() first to
2f960 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c   force the resul
2f970 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65  t.** into the de
2f980 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68  sired format, th
2f990 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  en invoke sqlite
2f9a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2f9b0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
2f9c0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2f9d0 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65  to find the size
2f9e0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20   of the result. 
2f9f0 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   Do not mix call
2fa00 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  s.** to sqlite3_
2fa10 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
2fa20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fa30 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c  blob() with call
2fa40 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
2fa50 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2fa60 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78  , and do not mix
2fa70 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2fa80 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2fa90 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20  ).** with calls 
2faa0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
2fab0 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a  n_bytes()..**.**
2fac0 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72   ^The pointers r
2fad0 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69  eturned are vali
2fae0 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63  d until a type c
2faf0 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
2fb00 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64   as.** described
2fb10 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c   above, or until
2fb20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2fb30 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
2fb40 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
2fb50 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2fb60 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54  ] is called.  ^T
2fb70 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20  he memory space 
2fb80 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72  used to hold str
2fb90 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42  ings.** and BLOB
2fba0 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d  s is freed autom
2fbb0 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62  atically.  Do <b
2fbc0 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68  >not</b> pass th
2fbd0 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
2fbe0 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
2fbf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2fc00 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ()], [sqlite3_co
2fc10 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74  lumn_text()], et
2fc20 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  c. into.** [sqli
2fc30 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
2fc40 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79  ** ^(If a memory
2fc50 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
2fc60 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
2fc70 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
2fc80 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
2fc90 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
2fca0 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
2fcb0 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
2fcc0 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
2fcd0 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
2fce0 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
2fcf0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
2fd00 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
2fd10 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
2fd20 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
2fd30 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
2fd40 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
2fd50 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
2fd60 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20  EM].)^.*/.const 
2fd70 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2fd80 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65  lumn_blob(sqlite
2fd90 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2fda0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2fdb0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c  column_bytes(sql
2fdc0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2fdd0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2fde0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2fdf0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2fe00 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62   int iCol);.doub
2fe10 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
2fe20 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
2fe30 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2fe40 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2fe50 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
2fe60 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2fe70 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  l);.sqlite3_int6
2fe80 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  4 sqlite3_column
2fe90 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
2fea0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2feb0 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
2fec0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2fed0 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
2fee0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2fef0 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  l);.const void *
2ff00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ff10 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
2ff20 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2ff30 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2ff40 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
2ff50 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2ff60 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  ;.sqlite3_value 
2ff70 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2ff80 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
2ff90 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2ffa0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ffb0 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61   Destroy A Prepa
2ffc0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
2ffd0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ject.**.** ^The 
2ffe0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2fff0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
30000 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20  alled to delete 
30010 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
30020 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74  ement]..** ^If t
30030 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
30040 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65  valuation of the
30050 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75   statement encou
30060 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73  ntered no errors
30070 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74  .** or if the st
30080 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72  atement is never
30090 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c   been evaluated,
300a0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69   then sqlite3_fi
300b0 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73  nalize() returns
300c0 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20  .** SQLITE_OK.  
300d0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
300e0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
300f0 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61  f statement S fa
30100 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  iled, then.** sq
30110 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
30120 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70  ) returns the ap
30130 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
30140 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
30150 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
30160 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  e]..**.** ^The s
30170 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
30180 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  S) routine can b
30190 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20  e called at any 
301a0 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20  point during.** 
301b0 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f  the life cycle o
301c0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
301d0 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66  ement] S:.** bef
301e0 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20  ore statement S 
301f0 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65  is ever evaluate
30200 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20  d, after.** one 
30210 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f  or more calls to
30220 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
30230 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79  )], or after any
30240 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c   call.** to [sql
30250 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67  ite3_step()] reg
30260 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
30270 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74  er or not the st
30280 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63  atement has.** c
30290 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69  ompleted executi
302a0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b  on..**.** ^Invok
302b0 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  ing sqlite3_fina
302c0 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c  lize() on a NULL
302d0 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61   pointer is a ha
302e0 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a  rmless no-op..**
302f0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
30300 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a  ion must finaliz
30310 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65  e every [prepare
30320 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
30330 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a  order to avoid.*
30340 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73  * resource leaks
30350 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76  .  It is a griev
30360 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68  ous error for th
30370 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  e application to
30380 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61   try to use.** a
30390 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
303a0 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
303b0 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e   been finalized.
303c0 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70    Any use of a p
303d0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
303e0 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
303f0 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
30400 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75   can result in u
30410 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20  ndefined and.** 
30420 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
30430 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67  vior such as seg
30440 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20  faults and heap 
30450 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69  corruption..*/.i
30460 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  nt sqlite3_final
30470 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ize(sqlite3_stmt
30480 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
30490 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
304a0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
304b0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ement Object.**.
304c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
304d0 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
304e0 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
304f0 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
30500 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
30510 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
30520 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
30530 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
30540 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20  ecuted..** ^Any 
30550 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
30560 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
30570 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
30580 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
30590 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
305a0 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
305b0 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
305c0 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
305d0 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
305e0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
305f0 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
30600 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
30610 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
30620 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
30630 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
30640 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30650 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f  nt] S.** back to
30660 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
30670 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
30680 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
30690 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
306a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
306b0 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
306c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
306d0 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
306e0 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
306f0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
30700 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
30710 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
30720 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
30730 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68  lled on S,.** th
30740 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
30750 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
30760 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
30770 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
30780 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
30790 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
307a0 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
307b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
307c0 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72   indicated an er
307d0 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71  ror, then.** [sq
307e0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
307f0 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
30800 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
30810 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
30820 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
30830 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
30840 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
30850 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e   values.** of an
30860 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
30870 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
30880 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
30890 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
308a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73  .int sqlite3_res
308b0 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  et(sqlite3_stmt 
308c0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
308d0 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65  CAPI3REF: Create
308e0 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c   Or Redefine SQL
308f0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45   Functions.** KE
30900 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f  YWORDS: {functio
30910 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
30920 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  nes}.** KEYWORDS
30930 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
30940 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
30950 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ion}.** KEYWORDS
30960 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
30970 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
30980 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions}.**.** ^The
30990 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f  se functions (co
309a0 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e  llectively known
309b0 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72   as "function cr
309c0 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22  eation routines"
309d0 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f  ).** are used to
309e0 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f   add SQL functio
309f0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
30a00 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20   or to redefine 
30a10 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
30a20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  of existing SQL 
30a30 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
30a40 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e  regates.  The on
30a50 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62  ly differences b
30a60 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20  etween.** these 
30a70 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65  routines are the
30a80 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65   text encoding e
30a90 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74  xpected for.** t
30aa0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
30ab0 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66  ter (the name of
30ac0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65   the function be
30ad0 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20  ing created).** 
30ae0 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65  and the presence
30af0 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61   or absence of a
30b00 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
30b10 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20  back for.** the 
30b20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
30b30 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
30b40 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
30b50 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74  eter is the [dat
30b60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
30b70 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53  ] to which the S
30b80 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  QL.** function i
30b90 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20  s to be added.  
30ba0 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ^If an applicati
30bb0 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61  on uses more tha
30bc0 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a  n one database.*
30bd0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65  * connection the
30be0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
30bf0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
30c00 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65  ons must be adde
30c10 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74  d.** to each dat
30c20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
30c30 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
30c40 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  ** ^The second p
30c50 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
30c60 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20  name of the SQL 
30c70 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63  function to be c
30c80 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64  reated or.** red
30c90 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65  efined.  ^The le
30ca0 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65  ngth of the name
30cb0 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32   is limited to 2
30cc0 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54  55 bytes in a UT
30cd0 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74  F-8.** represent
30ce0 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65  ation, exclusive
30cf0 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   of the zero-ter
30d00 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20  minator.  ^Note 
30d10 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a  that the name.**
30d20 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73   length limit is
30d30 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c   in UTF-8 bytes,
30d40 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20   not characters 
30d50 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73  nor UTF-16 bytes
30d60 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65  .  .** ^Any atte
30d70 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
30d80 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
30d90 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
30da0 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53  ill result in [S
30db0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65  QLITE_MISUSE] be
30dc0 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  ing returned..**
30dd0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70  .** ^The third p
30de0 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a  arameter (nArg).
30df0 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ** is the number
30e00 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68   of arguments th
30e10 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  at the SQL funct
30e20 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
30e30 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74  ate takes. ^If t
30e40 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
30e50 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51   -1, then the SQ
30e60 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
30e70 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74   aggregate may t
30e80 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ake any number o
30e90 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77  f arguments betw
30ea0 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69  een 0 and the li
30eb0 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73  mit.** set by [s
30ec0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
30ed0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
30ee0 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20  TION_ARG]).  If 
30ef0 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
30f00 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74  ameter is less t
30f10 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65  han -1 or greate
30f20 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20  r than 127 then 
30f30 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a  the behavior is.
30f40 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
30f50 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
30f60 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74  parameter, eText
30f70 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77  Rep, specifies w
30f80 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  hat.** [SQLITE_U
30f90 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
30fa0 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
30fb0 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
30fc0 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
30fd0 74 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69  ters.  The appli
30fe0 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65  cation should se
30ff0 74 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  t this parameter
31000 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55   to.** [SQLITE_U
31010 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66  TF16LE] if the f
31020 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
31030 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a  tation invokes .
31040 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
31050 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e  e_text16le()] on
31060 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53   an input, or [S
31070 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69  QLITE_UTF16BE] i
31080 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
31090 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  ntation invokes 
310a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
310b0 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e  ext16be()] on an
310c0 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53   input, or.** [S
310d0 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20  QLITE_UTF16] if 
310e0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
310f0 65 78 74 31 36 28 29 5d 20 69 73 20 75 73 65 64  ext16()] is used
31100 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
31110 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e  8].** otherwise.
31120 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20    ^The same SQL 
31130 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
31140 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69  registered multi
31150 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a  ple times using.
31160 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72 65  ** different pre
31170 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
31180 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66  dings, with diff
31190 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61  erent implementa
311a0 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63  tions for.** eac
311b0 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e  h encoding..** ^
311c0 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d  When multiple im
311d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
311e0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
311f0 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65  on are available
31200 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  , SQLite.** will
31210 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68   pick the one th
31220 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20  at involves the 
31230 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
31240 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  data conversion.
31250 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
31260 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  th parameter may
31270 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f   optionally be O
31280 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  Red with [SQLITE
31290 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a  _DETERMINISTIC].
312a0 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61  ** to signal tha
312b0 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77  t the function w
312c0 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72  ill always retur
312d0 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c  n the same resul
312e0 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73  t given.** the s
312f0 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68 69  ame inputs withi
31300 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  n a single SQL s
31310 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20  tatement.  Most 
31320 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  SQL functions ar
31330 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74  e.** determinist
31340 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69  ic.  The built-i
31350 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c  n [random()] SQL
31360 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20   function is an 
31370 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20  example of a.** 
31380 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73  function that is
31390 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74   not determinist
313a0 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20  ic.  The SQLite 
313b0 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73  query planner is
313c0 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66   able to.** perf
313d0 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f  orm additional o
313e0 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20  ptimizations on 
313f0 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75  deterministic fu
31400 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a  nctions, so use.
31410 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  ** of the [SQLIT
31420 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d  E_DETERMINISTIC]
31430 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65   flag is recomme
31440 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73 73 69  nded where possi
31450 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ble..**.** ^(The
31460 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
31470 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
31480 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69   pointer.  The i
31490 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
314a0 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
314b0 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73   can gain access
314c0 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72   to this pointer
314d0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
314e0 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a  user_data()].)^.
314f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68  **.** ^The sixth
31500 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69  , seventh and ei
31510 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c  ghth parameters,
31520 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e   xFunc, xStep an
31530 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a  d xFinal, are.**
31540 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c   pointers to C-l
31550 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e  anguage function
31560 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
31570 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
31580 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
31590 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c  e. ^A scalar SQL
315a0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
315b0 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
315c0 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e  tion of the xFun
315d0 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e  c.** callback on
315e0 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ly; NULL pointer
315f0 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  s must be passed
31600 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e   as the xStep an
31610 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61  d xFinal.** para
31620 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72  meters. ^An aggr
31630 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
31640 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
31650 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
31660 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46   xStep.** and xF
31670 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f  inal and NULL po
31680 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61  inter must be pa
31690 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20  ssed for xFunc. 
316a0 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78  ^To delete an ex
316b0 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75  isting.** SQL fu
316c0 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
316d0 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70  ate, pass NULL p
316e0 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20  ointers for all 
316f0 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  three function.*
31700 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a  * callbacks..**.
31710 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74  ** ^(If the nint
31720 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
31730 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
31740 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e  nction_v2() is n
31750 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e  ot NULL,.** then
31760 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f   it is destructo
31770 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63  r for the applic
31780 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
31790 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74  er. .** The dest
317a0 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65  ructor is invoke
317b0 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74  d when the funct
317c0 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20  ion is deleted, 
317d0 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a  either by being.
317e0 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72  ** overloaded or
317f0 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
31800 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
31810 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20  oses.)^.** ^The 
31820 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c  destructor is al
31830 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68  so invoked if th
31840 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  e call to.** sql
31850 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
31860 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e  tion_v2() fails.
31870 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65  .** ^When the de
31880 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
31890 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70  k of the tenth p
318a0 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f  arameter is invo
318b0 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61  ked, it.** is pa
318c0 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72  ssed a single ar
318d0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
318e0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70  a copy of the ap
318f0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a  plication data .
31900 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  ** pointer which
31910 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70   was the fifth p
31920 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
31930 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
31940 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  ion_v2()..**.** 
31950 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64  ^It is permitted
31960 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c   to register mul
31970 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
31980 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
31990 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77  e.** functions w
319a0 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
319b0 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65  e but with eithe
319c0 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62  r differing numb
319d0 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65  ers of.** argume
319e0 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67  nts or differing
319f0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
31a00 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c  encodings.  ^SQL
31a10 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
31a20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
31a30 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f  on that most clo
31a40 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65  sely matches the
31a50 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68   way in which th
31a60 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  e.** SQL functio
31a70 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66  n is used.  ^A f
31a80 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
31a90 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
31aa0 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41  n-negative.** nA
31ab0 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rg parameter is 
31ac0 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74  a better match t
31ad0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69  han a function i
31ae0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
31af0 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65  th.** a negative
31b00 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74   nArg.  ^A funct
31b10 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72  ion where the pr
31b20 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
31b30 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73  oding.** matches
31b40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
31b50 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74  coding is a bett
31b60 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e  er.** match than
31b70 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
31b80 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69  e the encoding i
31b90 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a  s different.  .*
31ba0 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68  * ^A function wh
31bb0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
31bc0 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62   difference is b
31bd0 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61  etween UTF16le a
31be0 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73  nd UTF16be.** is
31bf0 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20   a closer match 
31c00 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
31c10 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
31c20 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
31c30 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38  .** between UTF8
31c40 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a   and UTF16..**.*
31c50 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63  * ^Built-in func
31c60 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65  tions may be ove
31c70 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61  rloaded by new a
31c80 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
31c90 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  ed functions..**
31ca0 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74  .** ^An applicat
31cb0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
31cc0 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
31cd0 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a  d to call other.
31ce0 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
31cf0 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20  aces.  However, 
31d00 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20  such calls must 
31d10 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65  not.** close the
31d20 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
31d30 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a  tion nor finaliz
31d40 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70  e or reset the p
31d50 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
31d60 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68  ment in which th
31d70 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  e function is ru
31d80 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nning..*/.int sq
31d90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
31da0 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
31db0 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
31dc0 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
31dd0 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
31de0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
31df0 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
31e00 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
31e10 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
31e20 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
31e30 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
31e40 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
31e50 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
31e60 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
31e70 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
31e80 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
31e90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
31ea0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
31eb0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
31ec0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
31ed0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
31ee0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
31ef0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
31f00 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
31f10 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
31f20 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
31f30 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
31f40 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
31f50 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
31f60 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
31f70 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
31f80 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
31f90 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
31fa0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
31fb0 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ction_v2(.  sqli
31fc0 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
31fd0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
31fe0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
31ff0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
32000 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
32010 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
32020 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32030 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
32040 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
32050 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
32060 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
32070 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
32080 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
32090 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
320a0 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
320b0 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  oy)(void*).);../
320c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
320d0 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a  ext Encodings.**
320e0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
320f0 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65  nt define intege
32100 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70  r codes that rep
32110 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f  resent the vario
32120 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  us.** text encod
32130 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62  ings supported b
32140 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  y SQLite..*/.#de
32150 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38  fine SQLITE_UTF8
32160 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
32170 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
32180 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65  6LE        2.#de
32190 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
321a0 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65  6BE        3.#de
321b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
321c0 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20  6          4    
321d0 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79  /* Use native by
321e0 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66  te order */.#def
321f0 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20  ine SQLITE_ANY  
32200 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f            5    /
32210 2a 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a  * Deprecated */.
32220 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
32230 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20  TF16_ALIGNED  8 
32240 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
32250 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f  eate_collation o
32260 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  nly */../*.** CA
32270 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e  PI3REF: Function
32280 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Flags.**.** The
32290 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79  se constants may
322a0 20 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65   be ORed togethe
322b0 72 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  r with the .** [
322c0 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72  SQLITE_UTF8 | pr
322d0 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
322e0 6f 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f  oding] as the fo
322f0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  urth argument.**
32300 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
32310 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
32320 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
32330 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20  _function16()], 
32340 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  or.** [sqlite3_c
32350 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
32360 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  2()]..*/.#define
32370 20 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e   SQLITE_DETERMIN
32380 49 53 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a  ISTIC    0x800..
32390 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
323a0 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74  Deprecated Funct
323b0 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54  ions.** DEPRECAT
323c0 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  ED.**.** These f
323d0 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65  unctions are [de
323e0 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f  precated].  In o
323f0 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e  rder to maintain
32400 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
32410 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68  mpatibility with
32420 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65   older code, the
32430 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e  se functions con
32440 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20  tinue .** to be 
32450 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65  supported.  Howe
32460 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61  ver, new applica
32470 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f  tions should avo
32480 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  id.** the use of
32490 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
324a0 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75  .  To help encou
324b0 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61  rage people to a
324c0 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68  void.** using th
324d0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77  ese functions, w
324e0 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20  e are not going 
324f0 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74  to tell you what
32500 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66   they do..*/.#if
32510 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  ndef SQLITE_OMIT
32520 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49  _DEPRECATED.SQLI
32530 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
32540 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  t sqlite3_aggreg
32550 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ate_count(sqlite
32560 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c  3_context*);.SQL
32570 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
32580 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72  nt sqlite3_expir
32590 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ed(sqlite3_stmt*
325a0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
325b0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
325c0 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e  _transfer_bindin
325d0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
325e0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  , sqlite3_stmt*)
325f0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
32600 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
32610 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76  global_recover(v
32620 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  oid);.SQLITE_DEP
32630 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c  RECATED void sql
32640 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61  ite3_thread_clea
32650 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  nup(void);.SQLIT
32660 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
32670 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
32680 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f  alarm(void(*)(vo
32690 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
326a0 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20  4,int),.        
326b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
326c0 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
326d0 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  4);.#endif../*.*
326e0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
326f0 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69  ining SQL Functi
32700 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c  on Parameter Val
32710 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  ues.**.** The C-
32720 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
32730 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
32740 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
32750 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
32760 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
32770 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
32780 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
32790 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
327a0 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
327b0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
327c0 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
327d0 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
327e0 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
327f0 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
32800 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
32810 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
32820 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
32830 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
32840 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
32850 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
32860 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
32870 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
32880 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
32890 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70  es..** The 3rd p
328a0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
328b0 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
328c0 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
328d0 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
328e0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
328f0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
32900 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
32910 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
32920 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
32930 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
32940 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
32950 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
32960 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
32970 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
32980 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
32990 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
329a0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
329b0 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
329c0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
329d0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
329e0 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
329f0 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
32a00 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
32a10 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
32a20 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
32a30 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
32a40 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
32a50 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  or..**.** ^These
32a60 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
32a70 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
32a80 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
32a90 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
32aa0 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
32ab0 68 61 74 20 74 68 65 73 65 20 72 6f 75 74 69 6e  hat these routin
32ac0 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
32ad0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
32ae0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
32af0 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73  t.** pointer ins
32b00 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74  tead of a [sqlit
32b10 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65  e3_stmt*] pointe
32b20 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72  r and an integer
32b30 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a   column number..
32b40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
32b50 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
32b60 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
32b70 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74  acts a UTF-16 st
32b80 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  ring.** in the n
32b90 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72  ative byte-order
32ba0 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63   of the host mac
32bb0 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  hine.  ^The.** s
32bc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
32bd0 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69  t16be() and sqli
32be0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
32bf0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  le() interfaces.
32c00 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31  ** extract UTF-1
32c10 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
32c20 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
32c30 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
32c40 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tively..**.** ^(
32c50 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
32c60 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29  e_numeric_type()
32c70 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
32c80 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20  pts to apply.** 
32c90 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79  numeric affinity
32ca0 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20   to the value.  
32cb0 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
32cc0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a  an attempt is.**
32cd0 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74   made to convert
32ce0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e   the value to an
32cf0 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61   integer or floa
32d00 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a  ting point.  If.
32d10 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72  ** such a conver
32d20 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65  sion is possible
32d30 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66   without loss of
32d40 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e   information (in
32d50 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c   other.** words,
32d60 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73   if the value is
32d70 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c   a string that l
32d80 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62  ooks like a numb
32d90 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  er).** then the 
32da0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65  conversion is pe
32db0 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77  rformed.  Otherw
32dc0 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f  ise no conversio
32dd0 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65  n occurs..** The
32de0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
32df0 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74   | datatype] aft
32e00 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  er conversion is
32e10 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a   returned.)^.**.
32e20 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61  ** Please pay pa
32e30 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69  rticular attenti
32e40 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74  on to the fact t
32e50 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20  hat the pointer 
32e60 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d  returned.** from
32e70 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
32e80 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
32e90 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
32ea0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
32eb0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
32ec0 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74  can be invalidat
32ed0 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65  ed by a subseque
32ee0 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
32ef0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
32f00 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  es()], [sqlite3_
32f10 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d  value_bytes16()]
32f20 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
32f30 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
32f40 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
32f50 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ext16()]..**.** 
32f60 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
32f70 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
32f80 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
32f90 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c  ad as.** the SQL
32fa0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73   function that s
32fb0 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c  upplied the [sql
32fc0 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72  ite3_value*] par
32fd0 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73  ameters..*/.cons
32fe0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
32ff0 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
33000 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
33010 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
33020 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
33030 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
33040 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73  _value_bytes16(s
33050 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
33060 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76  double sqlite3_v
33070 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69  alue_double(sqli
33080 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
33090 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
330a0 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
330b0 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  *);.sqlite3_int6
330c0 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  4 sqlite3_value_
330d0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
330e0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  lue*);.const uns
330f0 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
33100 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73  te3_value_text(s
33110 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
33120 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
33130 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
33140 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
33150 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
33160 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
33170 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
33180 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
33190 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
331a0 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
331b0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
331c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
331d0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
331e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
331f0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
33200 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
33210 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33220 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67  F: Obtain Aggreg
33230 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  ate Function Con
33240 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65  text.**.** Imple
33250 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67  mentations of ag
33260 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
33270 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a  tions use this.*
33280 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c  * routine to all
33290 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72  ocate memory for
332a0 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73   storing their s
332b0 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tate..**.** ^The
332c0 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20   first time the 
332d0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
332e0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
332f0 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
33300 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69   .** for a parti
33310 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20  cular aggregate 
33320 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65  function, SQLite
33330 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20  .** allocates N 
33340 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65  of memory, zeroe
33350 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72  s out that memor
33360 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  y, and returns a
33370 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
33380 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e  he new memory. ^
33390 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  On second and su
333a0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
333b0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67  o.** sqlite3_agg
333c0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
333d0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67   for the same ag
333e0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
333f0 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68   instance,.** th
33400 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73  e same buffer is
33410 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69   returned.  Sqli
33420 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
33430 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61  ntext() is norma
33440 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e  lly.** called on
33450 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f  ce for each invo
33460 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53  cation of the xS
33470 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64  tep callback and
33480 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73   then one.** las
33490 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20  t time when the 
334a0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20  xFinal callback 
334b0 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57  is invoked.  ^(W
334c0 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63  hen no rows matc
334d0 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74  h.** an aggregat
334e0 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74  e query, the xSt
334f0 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66  ep() callback of
33500 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66   the aggregate f
33510 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65  unction.** imple
33520 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76  mentation is nev
33530 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46  er called and xF
33540 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64  inal() is called
33550 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a   exactly once..*
33560 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73  * In those cases
33570 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  , sqlite3_aggreg
33580 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69  ate_context() mi
33590 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f  ght be called fo
335a0 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  r the.** first t
335b0 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  ime from within 
335c0 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a  xFinal().)^.**.*
335d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61  * ^The sqlite3_a
335e0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
335f0 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65  (C,N) routine re
33600 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
33610 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69  nter .** when fi
33620 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20  rst called if N 
33630 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  is less than or 
33640 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72  equal to zero or
33650 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20   if a memory.** 
33660 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f  allocate error o
33670 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ccurs..**.** ^(T
33680 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61  he amount of spa
33690 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ce allocated by 
336a0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
336b0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69  e_context(C,N) i
336c0 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20  s.** determined 
336d0 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  by the N paramet
336e0 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63  er on first succ
336f0 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68  essful call.  Ch
33700 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61  anging the.** va
33710 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73  lue of N in subs
33720 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73  equent call to s
33730 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
33740 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69  _context() withi
33750 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67  n.** the same ag
33760 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
33770 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e   instance will n
33780 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65  ot resize the me
33790 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
337a0 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68  on.)^  Within th
337b0 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  e xFinal callbac
337c0 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61  k, it is customa
337d0 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30  ry to set.** N=0
337e0 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c   in calls to sql
337f0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
33800 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74  ontext(C,N) so t
33810 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74  hat no .** point
33820 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  less memory allo
33830 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a  cations occur..*
33840 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74  *.** ^SQLite aut
33850 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73  omatically frees
33860 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
33870 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  cated by .** sql
33880 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
33890 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68  ontext() when th
338a0 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  e aggregate quer
338b0 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a  y concludes..**.
338c0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
338d0 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61  ameter must be a
338e0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
338f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
33900 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20   | SQL function 
33910 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73  context] that is
33920 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
33930 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78  eter.** to the x
33940 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63  Step or xFinal c
33950 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
33960 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
33970 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a  the aggregate.**
33980 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
33990 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
339a0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
339b0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
339c0 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
339d0 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  e aggregate SQL 
339e0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
339f0 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
33a00 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
33a10 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f  context(sqlite3_
33a20 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42  context*, int nB
33a30 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ytes);../*.** CA
33a40 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74  PI3REF: User Dat
33a50 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  a For Functions.
33a60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33a70 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69  e3_user_data() i
33a80 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
33a90 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
33aa0 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77  e pointer that w
33ab0 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61  as the pUserData
33ac0 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
33ad0 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  5th parameter).*
33ae0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
33af0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
33b00 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
33b10 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33b20 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
33b30 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
33b40 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
33b50 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
33b60 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
33b70 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
33b80 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
33b90 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
33ba0 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
33bb0 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  ch.** the applic
33bc0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
33bd0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
33be0 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
33bf0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71  te3_user_data(sq
33c00 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
33c10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33c20 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
33c30 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69  ction For Functi
33c40 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
33c50 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
33c60 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72  b_handle() inter
33c70 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
33c80 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
33c90 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61  inter to the [da
33ca0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33cb0 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61  n] (the 1st para
33cc0 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
33cd0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33ce0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
33cf0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
33d00 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
33d10 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
33d20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
33d30 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
33d40 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
33d50 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71   function..*/.sq
33d60 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
33d70 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
33d80 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33d90 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
33da0 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
33db0 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a  xiliary Data.**.
33dc0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
33dd0 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62  ns may be used b
33de0 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65  y (non-aggregate
33df0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  ) SQL functions 
33e00 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
33e10 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72  metadata with ar
33e20 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49  gument values. I
33e30 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  f the same value
33e40 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a   is passed to.**
33e50 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61   multiple invoca
33e60 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
33e70 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64  e SQL function d
33e80 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63  uring query exec
33e90 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20  ution, under.** 
33ea0 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63  some circumstanc
33eb0 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  es the associate
33ec0 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62  d metadata may b
33ed0 65 20 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e  e preserved.  An
33ee0 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77   example.** of w
33ef0 68 65 72 65 20 74 68 69 73 20 6d 69 67 68 74 20  here this might 
33f00 62 65 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20  be useful is in 
33f10 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73  a regular-expres
33f20 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a  sion matching.**
33f30 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
33f40 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
33f50 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
33f60 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
33f70 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65   stored as.** me
33f80 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
33f90 64 20 77 69 74 68 20 74 68 65 20 70 61 74 74 65  d with the patte
33fa0 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20  rn string.  .** 
33fb0 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20  Then as long as 
33fc0 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69  the pattern stri
33fd0 6e 67 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73  ng remains the s
33fe0 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70  ame,.** the comp
33ff0 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70  iled regular exp
34000 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72  ression can be r
34010 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c  eused on multipl
34020 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
34030 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
34040 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ction..**.** ^Th
34050 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
34060 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
34070 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
34080 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64  ter to the metad
34090 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
340a0 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
340b0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66  _set_auxdata() f
340c0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65  unction with the
340d0 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   Nth argument.**
340e0 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70   value to the ap
340f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
34100 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20  d function. ^If 
34110 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61  there is no meta
34120 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74  data.** associat
34130 65 64 20 77 69 74 68 20 74 68 65 20 66 75 6e 63  ed with the func
34140 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74  tion argument, t
34150 68 69 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  his sqlite3_get_
34160 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
34170 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  ace.** returns a
34180 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
34190 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
341a0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
341b0 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65  N,P,X) interface
341c0 20 73 61 76 65 73 20 50 20 61 73 20 6d 65 74 61   saves P as meta
341d0 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74  data for the N-t
341e0 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66  h.** argument of
341f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34200 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
34210 6e 2e 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a  n.  ^Subsequent.
34220 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
34230 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
34240 43 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72  C,N) return P fr
34250 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  om the most rece
34260 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65  nt.** sqlite3_se
34270 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
34280 58 29 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d  X) call if the m
34290 65 74 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c  etadata is still
342a0 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c   valid or.** NUL
342b0 4c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74  L if the metadat
342c0 61 20 68 61 73 20 62 65 65 6e 20 64 69 73 63 61  a has been disca
342d0 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20  rded..** ^After 
342e0 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  each call to sql
342f0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
34300 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 20  (C,N,P,X) where 
34310 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a  X is not NULL,.*
34320 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  * SQLite will in
34330 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
34340 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 77  tor function X w
34350 69 74 68 20 70 61 72 61 6d 65 74 65 72 20 50 20  ith parameter P 
34360 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c  exactly.** once,
34370 20 77 68 65 6e 20 74 68 65 20 6d 65 74 61 64 61   when the metada
34380 74 61 20 69 73 20 64 69 73 63 61 72 64 65 64 2e  ta is discarded.
34390 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72  .** SQLite is fr
343a0 65 65 20 74 6f 20 64 69 73 63 61 72 64 20 74 68  ee to discard th
343b0 65 20 6d 65 74 61 64 61 74 61 20 61 74 20 61 6e  e metadata at an
343c0 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e  y time, includin
343d0 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  g: <ul>.** <li> 
343e0 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  when the corresp
343f0 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  onding function 
34400 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65  parameter change
34410 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68  s, or.** <li> wh
34420 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
34430 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
34440 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20  _finalize()] is 
34450 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a  called for the.*
34460 2a 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65  *      SQL state
34470 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ment, or.** <li>
34480 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 65   when sqlite3_se
34490 74 5f 61 75 78 64 61 74 61 28 29 20 69 73 20 69  t_auxdata() is i
344a0 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20  nvoked again on 
344b0 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74  the same paramet
344c0 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64  er, or.** <li> d
344d0 75 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e  uring the origin
344e0 61 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  al sqlite3_set_a
344f0 75 78 64 61 74 61 28 29 20 63 61 6c 6c 20 77 68  uxdata() call wh
34500 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20  en a memory .** 
34510 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20       allocation 
34520 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f  error occurs. </
34530 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ul>)^.**.** Note
34540 20 74 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 74   the last bullet
34550 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 2e 20   in particular. 
34560 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
34570 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33  X in .** sqlite3
34580 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
34590 2c 50 2c 58 29 20 6d 69 67 68 74 20 62 65 20 63  ,P,X) might be c
345a0 61 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  alled immediatel
345b0 79 2c 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a  y, before the.**
345c0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
345d0 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
345e0 20 65 76 65 6e 20 72 65 74 75 72 6e 73 2e 20 20   even returns.  
345f0 48 65 6e 63 65 20 73 71 6c 69 74 65 33 5f 73 65  Hence sqlite3_se
34600 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 73  t_auxdata().** s
34610 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20  hould be called 
34620 6e 65 61 72 20 74 68 65 20 65 6e 64 20 6f 66 20  near the end of 
34630 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  the function imp
34640 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20  lementation and 
34650 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
34660 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
34670 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61  hould not make a
34680 6e 79 20 75 73 65 20 6f 66 20 50 20 61 66 74 65  ny use of P afte
34690 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  r.** sqlite3_set
346a0 5f 61 75 78 64 61 74 61 28 29 20 68 61 73 20 62  _auxdata() has b
346b0 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a  een called..**.*
346c0 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c  * ^(In practice,
346d0 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65   metadata is pre
346e0 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66  served between f
346f0 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f  unction calls fo
34700 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61  r.** function pa
34710 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72  rameters that ar
34720 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63  e compile-time c
34730 6f 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64  onstants, includ
34740 69 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76  ing literal.** v
34750 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d  alues and [param
34760 65 74 65 72 73 5d 20 61 6e 64 20 65 78 70 72 65  eters] and expre
34770 73 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20  ssions composed 
34780 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e  from the same.)^
34790 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
347a0 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
347b0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
347c0 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
347d0 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  ch.** the SQL fu
347e0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
347f0 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
34800 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
34810 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34820 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73  , int N);.void s
34830 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
34840 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
34850 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64  xt*, int N, void
34860 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
34870 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
34880 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
34890 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
348a0 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
348b0 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73  avior.**.** Thes
348c0 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61  e are special va
348d0 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73  lues for the des
348e0 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20  tructor that is 
348f0 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
34900 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65  .** final argume
34910 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  nt to routines l
34920 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ike [sqlite3_res
34930 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49  ult_blob()].  ^I
34940 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
34950 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
34960 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
34970 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
34980 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
34990 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
349a0 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
349b0 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
349c0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
349d0 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a  estroyed.  ^The.
349e0 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ** SQLITE_TRANSI
349f0 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20  ENT value means 
34a00 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
34a10 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61   will likely cha
34a20 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65  nge in.** the ne
34a30 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68  ar future and th
34a40 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64  at SQLite should
34a50 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72   make its own pr
34a60 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a  ivate copy of.**
34a70 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66   the content bef
34a80 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
34a90 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66  *.** The typedef
34aa0 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f   is necessary to
34ab0 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f   work around pro
34ac0 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e  blems in certain
34ad0 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72  .** C++ compiler
34ae0 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f  s..*/.typedef vo
34af0 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73  id (*sqlite3_des
34b00 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f  tructor_type)(vo
34b10 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51  id*);.#define SQ
34b20 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20  LITE_STATIC     
34b30 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
34b40 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64  uctor_type)0).#d
34b50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
34b60 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74  NSIENT   ((sqlit
34b70 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
34b80 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  pe)-1)../*.** CA
34b90 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20  PI3REF: Setting 
34ba0 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e  The Result Of An
34bb0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a   SQL Function.**
34bc0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
34bd0 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74  es are used by t
34be0 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e  he xFunc or xFin
34bf0 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  al callbacks tha
34c00 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53  t.** implement S
34c10 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
34c20 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65   aggregates.  Se
34c30 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  e.** [sqlite3_cr
34c40 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
34c50 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
34c60 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
34c70 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69  )].** for additi
34c80 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
34c90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  ..**.** These fu
34ca0 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72  nctions work ver
34cb0 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20  y much like the 
34cc0 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  [parameter bindi
34cd0 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ng] family of.**
34ce0 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20   functions used 
34cf0 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74  to bind values t
34d00 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  o host parameter
34d10 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74  s in prepared st
34d20 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66  atements..** Ref
34d30 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70  er to the [SQL p
34d40 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65  arameter] docume
34d50 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
34d60 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
34d70 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
34d80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
34d90 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ob() interface s
34da0 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
34db0 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
34dc0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
34dd0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
34de0 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74   BLOB whose cont
34df0 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a  ent is pointed.*
34e00 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f  * to by the seco
34e10 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
34e20 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65   which is N byte
34e30 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69  s long where N i
34e40 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  s the.** third p
34e50 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
34e60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
34e70 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69  ult_zeroblob() i
34e80 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68  nterfaces set th
34e90 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
34ea0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
34eb0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
34ec0 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e  to be a BLOB con
34ed0 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f  taining all zero
34ee0 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20  .** bytes and N 
34ef0 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77  bytes in size, w
34f00 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61  here N is the va
34f10 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70  lue of the 2nd p
34f20 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
34f30 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
34f40 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74  ult_double() int
34f50 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
34f60 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
34f70 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
34f80 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
34f90 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20  o be a floating 
34fa0 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63  point value spec
34fb0 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20  ified.** by its 
34fc0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
34fd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34fe0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
34ff0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
35000 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e  lt_error16() fun
35010 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20  ctions.** cause 
35020 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  the implemented 
35030 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
35040 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69  throw an excepti
35050 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  on..** ^SQLite u
35060 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70  ses the string p
35070 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
35080 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65  .** 2nd paramete
35090 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73  r of sqlite3_res
350a0 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73  ult_error() or s
350b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
350c0 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68  ror16().** as th
350d0 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72  e text of an err
350e0 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51  or message.  ^SQ
350f0 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
35100 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
35110 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d  sage string from
35120 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35130 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38  error() as UTF-8
35140 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74  . ^SQLite.** int
35150 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69  erprets the stri
35160 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
35170 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
35180 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61   as UTF-16 in na
35190 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64  tive.** byte ord
351a0 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69  er.  ^If the thi
351b0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
351c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
351d0 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
351e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
351f0 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76  r16() is negativ
35200 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
35210 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72  kes as the error
35220 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20  .** message all 
35230 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20  text up through 
35240 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
35250 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
35260 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
35270 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
35280 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
35290 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  r.** sqlite3_res
352a0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
352b0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68   non-negative th
352c0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
352d0 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74  that many.** byt
352e0 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
352f0 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  rs) from the 2nd
35300 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
35310 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
35320 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35330 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
35340 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
35350 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
35360 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20  routines make a 
35370 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
35380 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
35390 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a  e text before.**
353a0 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48   they return.  H
353b0 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e  ence, the callin
353c0 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64  g function can d
353d0 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20  eallocate or.** 
353e0 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20  modify the text 
353f0 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72  after they retur
35400 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  n without harm..
35410 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35420 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
35430 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61  e() function cha
35440 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63  nges the error c
35450 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  ode.** returned 
35460 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72  by SQLite as a r
35470 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f  esult of an erro
35480 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  r in a function.
35490 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a    ^By default,.*
354a0 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  * the error code
354b0 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   is SQLITE_ERROR
354c0 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74  .  ^A subsequent
354d0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
354e0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
354f0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
35500 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72  sult_error16() r
35510 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20  esets the error 
35520 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45  code to SQLITE_E
35530 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  RROR..**.** ^The
35540 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35550 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69  error_toobig() i
35560 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
35570 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
35580 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69  an.** error indi
35590 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74  cating that a st
355a0 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20  ring or BLOB is 
355b0 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72  too long to repr
355c0 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  esent..**.** ^Th
355d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
355e0 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69  _error_nomem() i
355f0 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
35600 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
35610 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69  an.** error indi
35620 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65  cating that a me
35630 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
35640 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  failed..**.** ^T
35650 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
35660 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63  t_int() interfac
35670 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
35680 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
35690 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
356a0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
356b0 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20  o be the 32-bit 
356c0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
356d0 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
356e0 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
356f0 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  t..** ^The sqlit
35700 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
35710 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
35720 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
35730 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
35740 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
35750 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
35760 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  he 64-bit signed
35770 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
35780 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
35790 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
357a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
357b0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e  result_null() in
357c0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
357d0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
357e0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
357f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
35800 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  tion to be NULL.
35810 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35820 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
35830 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ), sqlite3_resul
35840 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73  t_text16(),.** s
35850 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
35860 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71  xt16le(), and sq
35870 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35880 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63  t16be() interfac
35890 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65  es.** set the re
358a0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
358b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
358c0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
358d0 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73  o be.** a text s
358e0 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72  tring which is r
358f0 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54  epresented as UT
35900 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69  F-8, UTF-16 nati
35910 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a  ve byte order,.*
35920 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20  * UTF-16 little 
35930 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31  endian, or UTF-1
35940 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65  6 big endian, re
35950 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
35960 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
35970 6c 74 5f 74 65 78 74 36 34 28 29 20 69 6e 74 65  lt_text64() inte
35980 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
35990 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61  eturn value of a
359a0 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  n.** application
359b0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
359c0 6e 20 74 6f 20 62 65 20 61 20 74 65 78 74 20 73  n to be a text s
359d0 74 72 69 6e 67 20 69 6e 20 61 6e 20 65 6e 63 6f  tring in an enco
359e0 64 69 6e 67 0a 2a 2a 20 73 70 65 63 69 66 69 65  ding.** specifie
359f0 64 20 62 79 20 74 68 65 20 66 69 66 74 68 20 28  d by the fifth (
35a00 61 6e 64 20 6c 61 73 74 29 20 70 61 72 61 6d 65  and last) parame
35a10 74 65 72 2c 20 77 68 69 63 68 20 6d 75 73 74 20  ter, which must 
35a20 62 65 20 6f 6e 65 0a 2a 2a 20 6f 66 20 5b 53 51  be one.** of [SQ
35a30 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
35a40 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c  ITE_UTF16], [SQL
35a50 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72  ITE_UTF16BE], or
35a60 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
35a70 5d 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61  ]..** ^SQLite ta
35a80 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73  kes the text res
35a90 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70  ult from the app
35aa0 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a  lication from.**
35ab0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
35ac0 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  er of the sqlite
35ad0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
35ae0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49  nterfaces..** ^I
35af0 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
35b00 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
35b10 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
35b20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
35b30 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
35b40 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73  SQLite takes res
35b50 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68  ult text from th
35b60 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  e 2nd parameter.
35b70 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  ** through the f
35b80 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
35b90 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
35ba0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
35bb0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
35bc0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
35bd0 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e  aces.** is non-n
35be0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73  egative, then as
35bf0 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74   many bytes (not
35c00 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20   characters) of 
35c10 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e  the text.** poin
35c20 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e  ted to by the 2n
35c30 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20  d parameter are 
35c40 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70  taken as the app
35c50 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
35c60 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73  .** function res
35c70 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33 72 64  ult.  If the 3rd
35c80 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f   parameter is no
35c90 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
35ca0 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74   it.** must be t
35cb0 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 20 69  he byte offset i
35cc0 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67 20 77  nto the string w
35cd0 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
35ce0 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a  minator would.**
35cf0 20 61 70 70 65 61 72 20 69 66 20 74 68 65 20 73   appear if the s
35d00 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55 4c 20  tring where NUL 
35d10 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20  terminated.  If 
35d20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65  any NUL characte
35d30 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  rs occur.** in t
35d40 68 65 20 73 74 72 69 6e 67 20 61 74 20 61 20 62  he string at a b
35d50 79 74 65 20 6f 66 66 73 65 74 20 74 68 61 74 20  yte offset that 
35d60 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65  is less than the
35d70 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 33 72   value of the 3r
35d80 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20  d.** parameter, 
35d90 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69  then the resulti
35da0 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 63  ng string will c
35db0 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
35dc0 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20  NULs and the.** 
35dd0 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73  result of expres
35de0 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67 20  sions operating 
35df0 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74 68 20  on strings with 
35e00 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73  embedded NULs is
35e10 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e   undefined..** ^
35e20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
35e30 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
35e40 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
35e50 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
35e60 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
35e70 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e  _blob is a non-N
35e80 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
35e90 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74  n SQLite calls t
35ea0 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  hat.** function 
35eb0 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  as the destructo
35ec0 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72  r on the text or
35ed0 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65   BLOB result whe
35ee0 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69  n it has.** fini
35ef0 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
35f00 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
35f10 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
35f20 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
35f30 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
35f40 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a  erfaces or to.**
35f50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35f60 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
35f70 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
35f80 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e  ITE_STATIC, then
35f90 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d   SQLite.** assum
35fa0 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74  es that the text
35fb0 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
35fc0 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73  is in constant s
35fd0 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
35fe0 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f  t.** copy the co
35ff0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72  ntent of the par
36000 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20  ameter nor call 
36010 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  a destructor on 
36020 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77  the content.** w
36030 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73  hen it has finis
36040 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
36050 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
36060 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
36070 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
36080 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
36090 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
360a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
360b0 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
360c0 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
360d0 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65  TRANSIENT.** the
360e0 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61  n SQLite makes a
360f0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73   copy of the res
36100 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f  ult into space o
36110 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  btained from.** 
36120 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
36130 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69  lloc()] before i
36140 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  t returns..**.**
36150 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
36160 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
36170 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
36180 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
36190 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
361a0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
361b0 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a   be a copy the.*
361c0 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
361d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
361e0 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62  ject specified b
361f0 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
36200 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ter.  ^The.** sq
36210 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
36220 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  ue() interface m
36230 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
36240 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
36250 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68  e].** so that th
36260 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
36270 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74  ] specified in t
36280 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
36290 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65   change or.** be
362a0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74   deallocated aft
362b0 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  er sqlite3_resul
362c0 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e  t_value() return
362d0 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  s without harm..
362e0 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64  ** ^A [protected
362f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
36300 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79  object may alway
36310 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20  s be used where 
36320 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
36330 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
36340 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75  ] object is requ
36350 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a  ired, so either.
36360 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69  ** kind of [sqli
36370 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
36380 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69  t can be used wi
36390 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  th this interfac
363a0 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73  e..**.** If thes
363b0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
363c0 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69  alled from withi
363d0 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20  n the different 
363e0 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74  thread.** than t
363f0 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e  he one containin
36400 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  g the applicatio
36410 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
36420 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64  on that received
36430 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
36440 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65  _context] pointe
36450 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  r, the results a
36460 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
36470 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
36480 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65  sult_blob(sqlite
36490 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
364a0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
364b0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
364c0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
364d0 6c 74 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65  lt_blob64(sqlite
364e0 33 5f 63 6f 6e 74 65 78 74 2a 2c 63 6f 6e 73 74  3_context*,const
364f0 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 75   void*,sqlite3_u
36500 69 6e 74 36 34 2c 76 6f 69 64 28 2a 29 28 76 6f  int64,void(*)(vo
36510 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
36520 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
36530 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
36540 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69  t*, double);.voi
36550 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
36560 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63  _error(sqlite3_c
36570 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
36580 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  har*, int);.void
36590 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
365a0 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f  error16(sqlite3_
365b0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
365c0 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
365d0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
365e0 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71  _error_toobig(sq
365f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
36600 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
36610 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
36620 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36630 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
36640 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
36650 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  de(sqlite3_conte
36660 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
36670 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
36680 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
36690 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
366a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
366b0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nt64(sqlite3_con
366c0 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69  text*, sqlite3_i
366d0 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt64);.void sqli
366e0 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
366f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36700 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
36710 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69  result_text(sqli
36720 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
36730 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20  nst char*, int, 
36740 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
36750 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
36760 73 75 6c 74 5f 74 65 78 74 36 34 28 73 71 6c 69  sult_text64(sqli
36770 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
36780 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
36790 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20  3_uint64,.      
367a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
367b0 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69       void(*)(voi
367c0 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68  d*), unsigned ch
367d0 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 76 6f  ar encoding);.vo
367e0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
367f0 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  t_text16(sqlite3
36800 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
36810 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
36820 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
36830 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36840 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  t_text16le(sqlit
36850 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
36860 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
36870 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
36880 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
36890 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  lt_text16be(sqli
368a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
368b0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
368c0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
368d0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
368e0 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ult_value(sqlite
368f0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
36900 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69  te3_value*);.voi
36910 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
36920 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
36930 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
36940 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
36950 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20  REF: Define New 
36960 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e  Collating Sequen
36970 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ces.**.** ^These
36980 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20   functions add, 
36990 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66  remove, or modif
369a0 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20  y a [collation] 
369b0 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
369c0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
369d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
369e0 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69  cified as the fi
369f0 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
36a00 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
36a10 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69   the collation i
36a20 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
36a30 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  .** for sqlite3_
36a40 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36a50 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
36a60 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
36a70 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54  v2().** and a UT
36a80 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
36a90 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
36aa0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
36ab0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
36ac0 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e  )..** ^Collation
36ad0 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70   names that comp
36ae0 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64  are equal accord
36af0 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ing to [sqlite3_
36b00 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a  strnicmp()] are.
36b10 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  ** considered to
36b20 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d   be the same nam
36b30 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74  e..**.** ^(The t
36b40 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65  hird argument (e
36b50 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65  TextRep) must be
36b60 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73   one of the cons
36b70 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  tants:.** <ul>.*
36b80 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
36b90 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  TF8],.** <li> [S
36ba0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a  QLITE_UTF16LE],.
36bb0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
36bc0 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69  UTF16BE],.** <li
36bd0 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  > [SQLITE_UTF16]
36be0 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
36bf0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
36c00 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  ED]..** </ul>)^.
36c10 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70  ** ^The eTextRep
36c20 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d   argument determ
36c30 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e  ines the encodin
36c40 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73  g of strings pas
36c50 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f  sed.** to the co
36c60 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
36c70 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c   callback, xCall
36c80 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  back..** ^The [S
36c90 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64  QLITE_UTF16] and
36ca0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
36cb0 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66  LIGNED] values f
36cc0 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66  or eTextRep.** f
36cd0 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20  orce strings to 
36ce0 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61  be UTF16 with na
36cf0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
36d00 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
36d10 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
36d20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52  value for eTextR
36d30 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67  ep forces string
36d40 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e  s to begin.** on
36d50 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64   an even byte ad
36d60 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dress..**.** ^Th
36d70 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
36d80 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61  t, pArg, is an a
36d90 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
36da0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
36db0 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67  passed.** throug
36dc0 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  h as the first a
36dd0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
36de0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
36df0 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  n callback..**.*
36e00 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
36e10 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b  ument, xCallback
36e20 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  , is a pointer t
36e30 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
36e40 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75  function..** ^Mu
36e50 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67  ltiple collating
36e60 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62   functions can b
36e70 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  e registered usi
36e80 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  ng the same name
36e90 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66   but.** with dif
36ea0 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20  ferent eTextRep 
36eb0 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53  parameters and S
36ec0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77  QLite will use w
36ed0 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63  hichever.** func
36ee0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68  tion requires th
36ef0 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
36f00 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d  f data transform
36f10 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68  ation..** ^If th
36f20 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75  e xCallback argu
36f30 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65  ment is NULL the
36f40 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  n the collating 
36f50 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64  function is.** d
36f60 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61  eleted.  ^When a
36f70 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ll collating fun
36f80 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68  ctions having th
36f90 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20  e same name are 
36fa0 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74  deleted,.** that
36fb0 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   collation is no
36fc0 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a   longer usable..
36fd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61  **.** ^The colla
36fe0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
36ff0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
37000 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66  d with a copy of
37010 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70   the pArg .** ap
37020 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
37030 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20  ointer and with 
37040 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74  two strings in t
37050 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
37060 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
37070 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e  eTextRep argumen
37080 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e  t.  The collatin
37090 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
370a0 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74  return an.** int
370b0 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67  eger that is neg
370c0 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20  ative, zero, or 
370d0 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74  positive.** if t
370e0 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20  he first string 
370f0 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71  is less than, eq
37100 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74  ual to, or great
37110 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f  er than the seco
37120 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  nd,.** respectiv
37130 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e  ely.  A collatin
37140 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
37150 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68  always return th
37160 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a  e same answer.**
37170 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20   given the same 
37180 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20  inputs.  If two 
37190 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e  or more collatin
371a0 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  g functions are 
371b0 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f  registered.** to
371c0 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74   the same collat
371d0 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20  ion name (using 
371e0 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52  different eTextR
371f0 65 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20  ep values) then 
37200 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65  all.** must give
37210 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61   an equivalent a
37220 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b  nswer when invok
37230 65 64 20 77 69 74 68 20 65 71 75 69 76 61 6c 65  ed with equivale
37240 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  nt strings..** T
37250 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
37260 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20  ction must obey 
37270 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72  the following pr
37280 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c  operties for all
37290 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42  .** strings A, B
372a0 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c  , and C:.**.** <
372b0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  ol>.** <li> If A
372c0 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a  ==B then B==A..*
372d0 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61  * <li> If A==B a
372e0 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d  nd B==C then A==
372f0 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26  C..** <li> If A&
37300 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41  lt;B THEN B&gt;A
37310 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c  ..** <li> If A&l
37320 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74  t;B and B&lt;C t
37330 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c  hen A&lt;C..** <
37340 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  /ol>.**.** If a 
37350 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
37360 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20  on fails any of 
37370 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72  the above constr
37380 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a  aints and that.*
37390 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  * collating func
373a0 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65  tion is  registe
373b0 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68  red and used, th
373c0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
373d0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20  of SQLite.** is 
373e0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
373f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72   ^The sqlite3_cr
37400 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
37410 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  2() works like s
37420 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
37430 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74  llation().** wit
37440 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74  h the addition t
37450 68 61 74 20 74 68 65 20 78 44 65 73 74 72 6f 79  hat the xDestroy
37460 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
37470 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65  oked on pArg whe
37480 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69  n.** the collati
37490 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  ng function is d
374a0 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c  eleted..** ^Coll
374b0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
374c0 61 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e  are deleted when
374d0 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69   they are overri
374e0 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a  dden by later.**
374f0 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f   calls to the co
37500 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  llation creation
37510 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68   functions or wh
37520 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  en the.** [datab
37530 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37540 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20  is closed using 
37550 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
37560 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44  ]..**.** ^The xD
37570 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20  estroy callback 
37580 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61  is <u>not</u> ca
37590 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20  lled if the .** 
375a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
375b0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75  ollation_v2() fu
375c0 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41  nction fails.  A
375d0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
375e0 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
375f0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
37600 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20  ion_v2() with a 
37610 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f  non-NULL xDestro
37620 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  y argument shoul
37630 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20  d .** check the 
37640 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20  return code and 
37650 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61  dispose of the a
37660 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
37670 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73  pointer.** thems
37680 65 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 61  elves rather tha
37690 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69  n expecting SQLi
376a0 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20  te to deal with 
376b0 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20  it for them..** 
376c0 54 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e  This is differen
376d0 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68  t from every oth
376e0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
376f0 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73  ace.  The incons
37700 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75  istency .** is u
37710 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63  nfortunate but c
37720 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
37730 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
37740 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20  g backwards .** 
37750 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
37760 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20  *.** See also:  
37770 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
37780 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64  on_needed()] and
37790 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
377a0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e  ion_needed16()].
377b0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
377c0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
377d0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
377e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
377f0 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
37800 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
37810 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
37820 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
37830 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
37840 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69  onst void*).);.i
37850 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
37860 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a  e_collation_v2(.
37870 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
37880 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
37890 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
378a0 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67  p, .  void *pArg
378b0 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
378c0 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
378d0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
378e0 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69  st void*),.  voi
378f0 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
37900 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  d*).);.int sqlit
37910 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
37920 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
37930 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  *, .  const void
37940 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65   *zName,.  int e
37950 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
37960 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
37970 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
37980 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
37990 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
379a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
379b0 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65  EF: Collation Ne
379c0 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  eded Callbacks.*
379d0 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68  *.** ^To avoid h
379e0 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65  aving to registe
379f0 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20  r all collation 
37a00 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65  sequences before
37a10 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63   a database.** c
37a20 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69  an be used, a si
37a30 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ngle callback fu
37a40 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
37a50 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68  gistered with th
37a60 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
37a70 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65  onnection] to be
37a80 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
37a90 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63  r an undefined c
37aa0 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
37ab0 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64  ence is required
37ac0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
37ad0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69  function is regi
37ae0 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
37af0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
37b00 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c  on_needed() API,
37b10 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70  .** then it is p
37b20 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20  assed the names 
37b30 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  of undefined col
37b40 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
37b50 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65   as strings.** e
37b60 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e  ncoded in UTF-8.
37b70 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c   ^If sqlite3_col
37b80 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
37b90 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68  ) is used,.** th
37ba0 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73  e names are pass
37bb0 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
37bc0 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62  machine native b
37bd0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41  yte order..** ^A
37be0 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20   call to either 
37bf0 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65  function replace
37c00 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63  s the existing c
37c10 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20  ollation-needed 
37c20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
37c30 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  ^(When the callb
37c40 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ack is invoked, 
37c50 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
37c60 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63  nt passed is a c
37c70 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65  opy.** of the se
37c80 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
37c90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
37ca0 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a  on_needed() or.*
37cb0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  * sqlite3_collat
37cc0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20  ion_needed16(). 
37cd0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
37ce0 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61  ment is the data
37cf0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
37d00 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  on.  The third a
37d10 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
37d20 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  f [SQLITE_UTF8],
37d30 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
37d40 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  ],.** or [SQLITE
37d50 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63  _UTF16LE], indic
37d60 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64  ating the most d
37d70 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66  esirable form of
37d80 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a   the collation.*
37d90 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74  * sequence funct
37da0 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54  ion required.  T
37db0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
37dc0 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
37dd0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72  of the.** requir
37de0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
37df0 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  uence.)^.**.** T
37e00 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
37e10 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69  tion should regi
37e20 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64  ster the desired
37e30 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67   collation using
37e40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
37e50 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d  ate_collation()]
37e60 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
37e70 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d  e_collation16()]
37e80 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
37e90 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
37ea0 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  n_v2()]..*/.int 
37eb0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
37ec0 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69  n_needed(.  sqli
37ed0 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20  te3*, .  void*, 
37ee0 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
37ef0 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
37f00 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61  extRep,const cha
37f10 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  r*).);.int sqlit
37f20 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
37f30 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ded16(.  sqlite3
37f40 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76  *, .  void*,.  v
37f50 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
37f60 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
37f70 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  ep,const void*).
37f80 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54  );..#ifdef SQLIT
37f90 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a  E_HAS_CODEC./*.*
37fa0 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65  * Specify the ke
37fb0 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74  y for an encrypt
37fc0 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68  ed database.  Th
37fd0 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  is routine shoul
37fe0 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72  d be.** called r
37ff0 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74  ight after sqlit
38000 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a  e3_open()..**.**
38010 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
38020 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
38030 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
38040 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
38050 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
38060 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
38070 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74  te3_key(.  sqlit
38080 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
38090 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
380a0 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
380b0 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
380c0 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
380d0 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b  Key     /* The k
380e0 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ey */.);.int sql
380f0 69 74 65 33 5f 6b 65 79 5f 76 32 28 0a 20 20 73  ite3_key_v2(.  s
38100 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
38110 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
38120 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
38130 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
38140 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65  st char *zDbName
38150 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
38160 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
38170 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  ase */.  const v
38180 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
38190 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b  Key     /* The k
381a0 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
381b0 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f  Change the key o
381c0 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  n an open databa
381d0 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72  se.  If the curr
381e0 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20  ent database is 
381f0 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64  not.** encrypted
38200 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  , this routine w
38210 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20  ill encrypt it. 
38220 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e   If pNew==0 or n
38230 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64  New==0, the.** d
38240 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79  atabase is decry
38250 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  pted..**.** The 
38260 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
38270 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
38280 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
38290 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
382a0 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
382b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
382c0 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20  ekey(.  sqlite3 
382d0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
382e0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
382f0 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
38300 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
38310 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
38320 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20       /* The new 
38330 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  key */.);.int sq
38340 6c 69 74 65 33 5f 72 65 6b 65 79 5f 76 32 28 0a  lite3_rekey_v2(.
38350 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
38360 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38370 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
38380 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
38390 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e  const char *zDbN
383a0 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20 2f  ame,           /
383b0 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  * Name of the da
383c0 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
383d0 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
383e0 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
383f0 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a  e new key */.);.
38400 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
38410 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65  he activation ke
38420 79 20 66 6f 72 20 61 20 53 45 45 20 64 61 74 61  y for a SEE data
38430 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a  base.  Unless .*
38440 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e  * activated, non
38450 65 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75  e of the SEE rou
38460 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e  tines will work.
38470 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
38480 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20  _activate_see(. 
38490 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
384a0 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20  ssPhrase        
384b0 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68  /* Activation ph
384c0 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69  rase */.);.#endi
384d0 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  f..#ifdef SQLITE
384e0 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a  _ENABLE_CEROD./*
384f0 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
38500 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66  activation key f
38510 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74 61 62  or a CEROD datab
38520 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a  ase.  Unless .**
38530 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65   activated, none
38540 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f   of the CEROD ro
38550 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b  utines will work
38560 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
38570 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64  3_activate_cerod
38580 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
38590 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20  zPassPhrase     
385a0 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e     /* Activation
385b0 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65   phrase */.);.#e
385c0 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
385d0 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78  3REF: Suspend Ex
385e0 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68  ecution For A Sh
385f0 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54  ort Time.**.** T
38600 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  he sqlite3_sleep
38610 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  () function caus
38620 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  es the current t
38630 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64  hread to suspend
38640 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f   execution.** fo
38650 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d  r at least a num
38660 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
38670 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e  nds specified in
38680 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a   its parameter..
38690 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65  **.** If the ope
386a0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f  rating system do
386b0 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73  es not support s
386c0 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69  leep requests wi
386d0 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e  th.** millisecon
386e0 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f  d time resolutio
386f0 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65  n, then the time
38700 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64   will be rounded
38710 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65   up to.** the ne
38720 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68  arest second. Th
38730 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
38740 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
38750 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65  p actually.** re
38760 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65  quested from the
38770 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
38780 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  m is returned..*
38790 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70  *.** ^SQLite imp
387a0 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74  lements this int
387b0 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e  erface by callin
387c0 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a  g the xSleep().*
387d0 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  * method of the 
387e0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
387f0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49  _vfs] object.  I
38800 66 20 74 68 65 20 78 53 6c