/ Hex Artifact Content
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Artifact 5fdc866a06ac82fd3c6ccb9f59a100151a36568c:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e  ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2f20: 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61  ) is called on a
2f30: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f40: 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c  ction] that stil
2f50: 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e  l has.** outstan
2f60: 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73  ding [prepared s
2f70: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f  tatements], [BLO
2f80: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f  B handles], and/
2f90: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  or.** [sqlite3_b
2fa0: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74  ackup] objects t
2fb0: 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53  hen it returns S
2fc0: 51 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65  QLITE_OK but the
2fd0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
2fe0: 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73   of resources is
2ff0: 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
3000: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
3010: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42  atements], [BLOB
3020: 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e   handles],.** an
3030: 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  d [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61  p] objects are a
3050: 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  lso destroyed..*
3060: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c  *.** ^If an [sql
3070: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
3080: 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20  destroyed while 
3090: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
30a0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
30b0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
30c0: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
30d0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
30e0: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
30f0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
3100: 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  C)] and [sqlite3
3110: 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a  _close_v2(C)].**
3120: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
3130: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
3140: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
3150: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
3160: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3170: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
3180: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
3190: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
31a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
31b0: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69  ], and not previ
31c0: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a  ously closed..**
31d0: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
31e0: 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c  3_close() or sql
31f0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
3200: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
3210: 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ter.** argument 
3220: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
3230: 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  -op..*/.int sqli
3240: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
3250: 33 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  3*);.int sqlite3
3260: 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65  _close_v2(sqlite
3270: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  3*);../*.** The 
3280: 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62  type for a callb
3290: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ack function..**
32a0: 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20   This is legacy 
32b0: 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20  and deprecated. 
32c0: 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20   It is included 
32d0: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a  for historical.*
32e0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
32f0: 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d  and is not docum
3300: 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65  ented..*/.typede
3310: 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f  f int (*sqlite3_
3320: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3330: 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72  int,char**, char
3340: 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  **);../*.** CAPI
3350: 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51  3REF: One-Step Q
3360: 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49  uery Execution I
3370: 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54  nterface.**.** T
3380: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3390: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61  ) interface is a
33a0: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61   convenience wra
33b0: 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
33c0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
33d0: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
33e0: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
33f0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
3400: 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77  ],.** that allow
3410: 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
3420: 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65   to run multiple
3430: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53   statements of S
3440: 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61  QL.** without ha
3450: 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f  ving to use a lo
3460: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a  t of C code. .**
3470: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
3480: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
3490: 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d  e runs zero or m
34a0: 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ore UTF-8 encode
34b0: 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  d,.** semicolon-
34c0: 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61  separate SQL sta
34d0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
34e0: 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75  nto its 2nd argu
34f0: 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20  ment,.** in the 
3500: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b  context of the [
3510: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3520: 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61  ion] passed in a
3530: 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67  s its 1st.** arg
3540: 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ument.  ^If the 
3550: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3560: 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67  n of the 3rd arg
3570: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
3580: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
3590: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20  t NULL, then it 
35a0: 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65  is invoked for e
35b0: 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a  ach result row.*
35c0: 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20  * coming out of 
35d0: 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51  the evaluated SQ
35e0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e  L statements.  ^
35f0: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
3600: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   to.** sqlite3_e
3610: 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64  xec() is relayed
3620: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
3630: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  1st argument of 
3640: 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  each.** callback
3650: 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49   invocation.  ^I
3660: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70  f the callback p
3670: 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
3680: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e  3_exec().** is N
3690: 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c  ULL, then no cal
36a0: 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e  lback is ever in
36b0: 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74  voked and result
36c0: 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e   rows are.** ign
36d0: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ored..**.** ^If 
36e0: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
36f0: 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
3700: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3710: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  nts passed into.
3720: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3730: 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f  ), then executio
3740: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
3750: 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73   statement stops
3760: 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65   and.** subseque
3770: 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  nt statements ar
3780: 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20  e skipped.  ^If 
3790: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
37a0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
37b0: 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  c().** is not NU
37c0: 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f  LL then any erro
37d0: 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69  r message is wri
37e0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
37f0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3800: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
3810: 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20  c()] and passed 
3820: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
3830: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a   5th parameter..
3840: 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f  ** To avoid memo
3850: 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70  ry leaks, the ap
3860: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
3870: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
3880: 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65  _free()].** on e
3890: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
38a0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68  ings returned th
38b0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
38c0: 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66  rameter of.** of
38d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38e0: 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20  after the error 
38f0: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
3900: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  s no longer need
3910: 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35  ed..** ^If the 5
3920: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3940: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e  s not NULL and n
3950: 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75  o errors.** occu
3960: 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
3970: 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20  exec() sets the 
3980: 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35  pointer in its 5
3990: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
39a0: 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72  ** NULL before r
39b0: 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
39c0: 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65  ^If an sqlite3_e
39d0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72  xec() callback r
39e0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
39f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3a00: 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  c().** routine r
3a10: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42  eturns SQLITE_AB
3a20: 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f  ORT without invo
3a30: 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63  king the callbac
3a40: 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77  k again and.** w
3a50: 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61  ithout running a
3a60: 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51  ny subsequent SQ
3a70: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
3a80: 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67  .** ^The 2nd arg
3a90: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3aa0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3ab0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73  back function is
3ac0: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
3ad0: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
3ae0: 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33   result.  ^The 3
3af0: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rd argument to t
3b00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3b10: 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73  ).** callback is
3b20: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3b30: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3b40: 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20   obtained as if 
3b50: 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
3b60: 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
3b70: 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f   one for each co
3b80: 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c  lumn.  ^If an el
3b90: 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65  ement of a.** re
3ba0: 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c  sult row is NULL
3bb0: 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   then the corres
3bc0: 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70  ponding string p
3bd0: 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a  ointer for the.*
3be0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
3bf0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e   callback is a N
3c00: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
3c10: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
3c20: 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  to the.** sqlite
3c30: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3c40: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3c50: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3c60: 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a  ings where each.
3c70: 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65  ** entry represe
3c80: 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  nts the name of 
3c90: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65  corresponding re
3ca0: 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f  sult column as o
3cb0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3cc0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
3cd0: 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  name()]..**.** ^
3ce0: 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
3cf0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3d00: 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c  exec() is a NULL
3d10: 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e   pointer, a poin
3d20: 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70  ter.** to an emp
3d30: 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20  ty string, or a 
3d40: 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e  pointer that con
3d50: 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65  tains only white
3d60: 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a  space and/or .**
3d70: 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74   SQL comments, t
3d80: 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65  hen no SQL state
3d90: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61  ments are evalua
3da0: 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61  ted and the data
3db0: 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  base.** is not c
3dc0: 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  hanged..**.** Re
3dd0: 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a  strictions:.**.*
3de0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
3df0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e00: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
3e10: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
3e20: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3e30: 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61  c().**      is a
3e40: 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20   valid and open 
3e50: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3e60: 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  tion]..** <li> T
3e70: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e80: 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64  ust not close [d
3e90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3ea0: 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
3eb0: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74  .**      the 1st
3ec0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3ed0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
3ee0: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
3ef0: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
3f00: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3f10: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d  ation must not m
3f20: 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74  odify the SQL st
3f30: 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73  atement text pas
3f40: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20  sed into.**     
3f50: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3f60: 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78  er of sqlite3_ex
3f70: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
3f80: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
3f90: 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  ning..** </ul>.*
3fa0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
3fb0: 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ec(.  sqlite3*, 
3fc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
3ff0: 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
4000: 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20  char *sql,      
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
4030: 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
4040: 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29   int (*callback)
4050: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
4060: 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43  *,char**),  /* C
4070: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
4080: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20   */.  void *,   
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74   /* 1st argument
40c0: 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a   to callback */.
40d0: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20    char **errmsg 
40e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
4100: 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
4110: 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  n here */.);../*
4120: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
4130: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  sult Codes.** KE
4140: 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f  YWORDS: SQLITE_O
4150: 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  K {error code} {
4160: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
4170: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4180: 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20  t code} {result 
4190: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e  codes}.**.** Man
41a0: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f  y SQLite functio
41b0: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74  ns return an int
41c0: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65  eger result code
41d0: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68   from the set sh
41e0: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f  own.** here in o
41f0: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  rder to indicate
4200: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
4210: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65  ure..**.** New e
4220: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62  rror codes may b
4230: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
4240: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
4250: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  Lite..**.** See 
4260: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
4270: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
4280: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4290: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  ],.** [sqlite3_v
42a0: 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
42b0: 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42  )] [SQLITE_ROLLB
42c0: 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  ACK | result cod
42d0: 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  es]..*/.#define 
42e0: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
42f0: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
4300: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
4310: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
4320: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
4330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
4340: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
4350: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
4360: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
4370: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4380: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
4390: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
43a0: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
43b0: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
43c0: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
43d0: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
43e0: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
43f0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4400: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
4410: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
4420: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
4430: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
4440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4450: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
4460: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
4470: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
4480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4490: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
44a0: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
44b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
44c0: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
44d0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
44e0: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
44f0: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4500: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4510: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
4520: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
4530: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
4540: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
4550: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
4560: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
4570: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
4580: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
4590: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
45a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
45b0: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
45c0: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
45d0: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
45e0: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
45f0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4600: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
4610: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
4620: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
4630: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4640: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
4650: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
4660: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
4670: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
4680: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4690: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
46a0: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
46b0: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
46c0: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
46d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
46e0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
46f0: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4700: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4710: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4720: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
4730: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
4740: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
4750: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
4760: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
4770: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
4780: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
4790: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
47a0: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
47b0: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
47c0: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
47d0: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
47e0: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
47f0: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4800: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4810: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4820: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4830: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
4840: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
4850: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
4860: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
4870: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
4880: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4890: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
48a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48b0: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
48c0: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
48d0: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
48e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
48f0: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4900: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4910: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4920: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
4930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
4940: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
4950: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
4960: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4970: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
4980: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4990: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
49a0: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
49b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
49c0: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
49d0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
49e0: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
49f0: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4a00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4a10: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4a20: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4a30: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4a40: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4a50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20  fine SQLITE_ROW 
4a60: 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20          100  /* 
4a70: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4a80: 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72  as another row r
4a90: 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  eady */.#define 
4aa0: 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20  SQLITE_DONE     
4ab0: 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74     101  /* sqlit
4ac0: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69  e3_step() has fi
4ad0: 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
4ae0: 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72   */./* end-of-er
4af0: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a  ror-codes */../*
4b00: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78  .** CAPI3REF: Ex
4b10: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
4b20: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
4b30: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
4b40: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
4b50: 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a   error codes}.**
4b60: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4b70: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4b80: 7d 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75  } {extended resu
4b90: 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20  lt codes}.**.** 
4ba0: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63  In its default c
4bb0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51  onfiguration, SQ
4bc0: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65  Lite API routine
4bd0: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  s return one of 
4be0: 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53  26 integer.** [S
4bf0: 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c  QLITE_OK | resul
4c00: 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76  t codes].  Howev
4c10: 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68  er, experience h
4c20: 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61  as shown that ma
4c30: 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72  ny of.** these r
4c40: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
4c50: 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e  too coarse-grain
4c60: 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74  ed.  They do not
4c70: 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d   provide as.** m
4c80: 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  uch information 
4c90: 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61  about problems a
4ca0: 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69  s programmers mi
4cb0: 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e  ght like.  In an
4cc0: 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64   effort to.** ad
4cd0: 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65  dress this, newe
4ce0: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
4cf0: 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e  Lite (version 3.
4d00: 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69  3.8 and later) i
4d10: 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72  nclude.** suppor
4d20: 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  t for additional
4d30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68   result codes th
4d40: 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20  at provide more 
4d50: 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61  detailed informa
4d60: 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72  tion.** about er
4d70: 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64  rors. The extend
4d80: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4d90: 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  are enabled or d
4da0: 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20  isabled.** on a 
4db0: 70 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e  per database con
4dc0: 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73  nection basis us
4dd0: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
4de0: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
4df0: 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49  ult_codes()] API
4e00: 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20  ..**.** Some of 
4e10: 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78  the available ex
4e20: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4e30: 64 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68  des are listed h
4e40: 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20  ere..** One may 
4e50: 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65  expect the numbe
4e60: 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65  r of extended re
4e70: 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20  sult codes will 
4e80: 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65  be expand.** ove
4e90: 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72  r time.  Softwar
4ea0: 65 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65  e that uses exte
4eb0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4ec0: 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a  s should expect.
4ed0: 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65  ** to see new re
4ee0: 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75  sult codes in fu
4ef0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
4f00: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
4f10: 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73  he SQLITE_OK res
4f20: 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65  ult code will ne
4f30: 76 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e  ver be extended.
4f40: 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73    It will always
4f50: 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a  .** be exactly z
4f60: 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ero..*/.#define 
4f70: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
4f80: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  D              (
4f90: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4fa0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
4fb0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
4fc0: 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53  T_READ        (S
4fd0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
4fe0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4ff0: 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45  LITE_IOERR_WRITE
5000: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5010: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c  LITE_IOERR | (3<
5020: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5030: 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20  ITE_IOERR_FSYNC 
5040: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5050: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c  ITE_IOERR | (4<<
5060: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5070: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59  TE_IOERR_DIR_FSY
5080: 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  NC         (SQLI
5090: 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38  TE_IOERR | (5<<8
50a0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50b0: 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45  E_IOERR_TRUNCATE
50c0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50d0: 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29  E_IOERR | (6<<8)
50e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
50f0: 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20  _IOERR_FSTAT    
5100: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5110: 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29  _IOERR | (7<<8))
5120: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5130: 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20  IOERR_UNLOCK    
5140: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5150: 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a  IOERR | (8<<8)).
5160: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5170: 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20  OERR_RDLOCK     
5180: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5190: 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23  OERR | (9<<8)).#
51a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51b0: 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ERR_DELETE      
51c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
51d0: 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23  ERR | (10<<8)).#
51e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51f0: 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20  ERR_BLOCKED     
5200: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5210: 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23  ERR | (11<<8)).#
5220: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5230: 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ERR_NOMEM       
5240: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5250: 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23  ERR | (12<<8)).#
5260: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5270: 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20  ERR_ACCESS      
5280: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5290: 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23  ERR | (13<<8)).#
52a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52b0: 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45  ERR_CHECKRESERVE
52c0: 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f  DLOCK (SQLITE_IO
52d0: 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23  ERR | (14<<8)).#
52e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52f0: 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  ERR_LOCK        
5300: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5310: 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23  ERR | (15<<8)).#
5320: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5330: 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  ERR_CLOSE       
5340: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5350: 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23  ERR | (16<<8)).#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5370: 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20  ERR_DIR_CLOSE   
5380: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5390: 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23  ERR | (17<<8)).#
53a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
53b0: 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20  ERR_SHMOPEN     
53c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
53d0: 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23  ERR | (18<<8)).#
53e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
53f0: 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20  ERR_SHMSIZE     
5400: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5410: 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23  ERR | (19<<8)).#
5420: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5430: 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20  ERR_SHMLOCK     
5440: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5450: 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23  ERR | (20<<8)).#
5460: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5470: 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20  ERR_SHMMAP      
5480: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5490: 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23  ERR | (21<<8)).#
54a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
54b0: 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20  ERR_SEEK        
54c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
54d0: 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23  ERR | (22<<8)).#
54e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
54f0: 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54  ERR_DELETE_NOENT
5500: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5510: 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23  ERR | (23<<8)).#
5520: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5530: 45 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20  ERR_MMAP        
5540: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5550: 45 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23  ERR | (24<<8)).#
5560: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
5570: 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45  CKED_SHAREDCACHE
5580: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f        (SQLITE_LO
5590: 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a  CKED |  (1<<8)).
55a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
55b0: 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20  USY_RECOVERY    
55c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42         (SQLITE_B
55d0: 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29  USY   |  (1<<8))
55e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55f0: 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44  CANTOPEN_NOTEMPD
5600: 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  IR      (SQLITE_
5610: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38  CANTOPEN | (1<<8
5620: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5630: 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52  E_CANTOPEN_ISDIR
5640: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5650: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c  E_CANTOPEN | (2<
5660: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5670: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c  ITE_CANTOPEN_FUL
5680: 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  LPATH       (SQL
5690: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
56a0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
56b0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
56c0: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
56d0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
56e0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
56f0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5700: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
5710: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5720: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5730: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5740: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
5750: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5760: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
5770: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5780: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5790: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
57a0: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
57b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
57c0: 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20  RT_ROLLBACK     
57d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f       (SQLITE_ABO
57e0: 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  RT | (2<<8)).#de
57f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5800: 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20  TRAINT_CHECK    
5810: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5820: 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29  TRAINT | (1<<8))
5830: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5840: 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49  CONSTRAINT_COMMI
5850: 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f  THOOK   (SQLITE_
5860: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c  CONSTRAINT | (2<
5870: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5880: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
5890: 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c  OREIGNKEY   (SQL
58a0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
58b0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
58c0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
58d0: 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  NT_FUNCTION     
58e0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
58f0: 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  NT | (4<<8)).#de
5900: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5910: 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20  TRAINT_NOTNULL  
5920: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5930: 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29  TRAINT | (5<<8))
5940: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5950: 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41  CONSTRAINT_PRIMA
5960: 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  RYKEY   (SQLITE_
5970: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c  CONSTRAINT | (6<
5980: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5990: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54  ITE_CONSTRAINT_T
59a0: 52 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c  RIGGER      (SQL
59b0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
59c0: 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (7<<8)).#define
59d0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
59e0: 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20  NT_UNIQUE       
59f0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5a00: 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  NT | (8<<8)).#de
5a10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5a20: 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20  TRAINT_VTAB     
5a30: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5a40: 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29  TRAINT | (9<<8))
5a50: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5a60: 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65  : Flags For File
5a70: 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73   Open Operations
5a80: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74  .**.** These bit
5a90: 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65   values are inte
5aa0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
5ab0: 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d  the.** 3rd param
5ac0: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
5ad0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
5ae0: 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a  interface and.**
5af0: 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61   in the 4th para
5b00: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5b10: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
5b20: 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66   method..*/.#def
5b30: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5b40: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20  READONLY        
5b50: 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20   0x00000001  /* 
5b60: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5b70: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5b80: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5b90: 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20  READWRITE       
5ba0: 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20   0x00000002  /* 
5bb0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5bc0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5bd0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5be0: 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20  CREATE          
5bf0: 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20   0x00000004  /* 
5c00: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5c10: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5c20: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5c30: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20  DELETEONCLOSE   
5c40: 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20   0x00000008  /* 
5c50: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5c60: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5c70: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20  EXCLUSIVE       
5c80: 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20   0x00000010  /* 
5c90: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5ca0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5cb0: 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20  AUTOPROXY       
5cc0: 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20   0x00000020  /* 
5cd0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5ce0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5cf0: 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20 20  URI             
5d00: 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 20   0x00000040  /* 
5d10: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5d20: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5d30: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5d40: 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20 20  MEMORY          
5d50: 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a 20   0x00000080  /* 
5d60: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5d70: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5d80: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5d90: 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20  MAIN_DB         
5da0: 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20   0x00000100  /* 
5db0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5dc0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5dd0: 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20  TEMP_DB         
5de0: 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20   0x00000200  /* 
5df0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5e00: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5e10: 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20  TRANSIENT_DB    
5e20: 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20   0x00000400  /* 
5e30: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5e40: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5e50: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  MAIN_JOURNAL    
5e60: 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20   0x00000800  /* 
5e70: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5e80: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5e90: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  TEMP_JOURNAL    
5ea0: 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20   0x00001000  /* 
5eb0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5ec0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5ed0: 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20  SUBJOURNAL      
5ee0: 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20   0x00002000  /* 
5ef0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5f00: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5f10: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20  MASTER_JOURNAL  
5f20: 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20   0x00004000  /* 
5f30: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5f40: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5f50: 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20  NOMUTEX         
5f60: 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20   0x00008000  /* 
5f70: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5f80: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5f90: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5fa0: 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20  FULLMUTEX       
5fb0: 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20   0x00010000  /* 
5fc0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5fd0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5fe0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5ff0: 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20  SHAREDCACHE     
6000: 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20   0x00020000  /* 
6010: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6020: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
6030: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6040: 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20  PRIVATECACHE    
6050: 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20   0x00040000  /* 
6060: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6070: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
6080: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6090: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  WAL             
60a0: 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20   0x00080000  /* 
60b0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20  VFS only */../* 
60c0: 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 20  Reserved:       
60d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
60e0: 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a    0x00F00000 */.
60f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6100: 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65   Device Characte
6110: 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68  ristics.**.** Th
6120: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
6130: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20  eristics method 
6140: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
6150: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f  io_methods].** o
6160: 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e  bject returns an
6170: 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
6180: 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68  s a vector of th
6190: 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65  ese.** bit value
61a0: 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f  s expressing I/O
61b0: 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73   characteristics
61c0: 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f   of the mass sto
61d0: 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74  rage.** device t
61e0: 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69  hat holds the fi
61f0: 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  le that the [sql
6200: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6210: 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a  .** refers to..*
6220: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
6230: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
6240: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6250: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
6260: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
6270: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
6280: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
6290: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
62a0: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
62b0: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
62c0: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
62d0: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
62e0: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
62f0: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
6300: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
6310: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
6320: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
6330: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6340: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
6350: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
6360: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
6370: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
6380: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
6390: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
63a0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
63b0: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
63c0: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
63d0: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
63e0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
63f0: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
6400: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
6410: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
6420: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
6430: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
6440: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
6450: 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68 65  o xWrite().  The
6460: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f   SQLITE_IOCAP_PO
6470: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
6480: 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  E property means
6490: 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72   that.** after r
64a0: 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20  eboot following 
64b0: 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72  a crash or power
64c0: 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20   loss, the only 
64d0: 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69  bytes in a.** fi
64e0: 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72 69  le that were wri
64f0: 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c  tten at the appl
6500: 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69  ication level mi
6510: 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65 64  ght have changed
6520: 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a  .** and that adj
6530: 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65  acent bytes, eve
6540: 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20 74  n bytes within t
6550: 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61  he same sector a
6560: 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64  re.** guaranteed
6570: 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64   to be unchanged
6580: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6590: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
65a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
65b0: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66   0x00000001.#def
65c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
65d0: 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20  _ATOMIC512      
65e0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
65f0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
6600: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
6610: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6620: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e  x00000004.#defin
6630: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6640: 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20  TOMIC2K         
6650: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38        0x00000008
6660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6670: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20  IOCAP_ATOMIC4K  
6680: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6690: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
66a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
66b0: 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20  MIC8K           
66c0: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23      0x00000020.#
66d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
66e0: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20  CAP_ATOMIC16K   
66f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6700: 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51  00040.#define SQ
6710: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6720: 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  C32K            
6730: 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65    0x00000080.#de
6740: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6750: 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20  P_ATOMIC64K     
6760: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6770: 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  100.#define SQLI
6780: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6790: 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20  PEND            
67a0: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
67b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
67c0: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
67d0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30         0x0000040
67e0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
67f0: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
6800: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78  LE_WHEN_OPEN  0x
6810: 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65  00000800.#define
6820: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f   SQLITE_IOCAP_PO
6830: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
6840: 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a  E    0x00001000.
6850: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6860: 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65   File Locking Le
6870: 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  vels.**.** SQLit
6880: 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68  e uses one of th
6890: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
68a0: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
68b0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
68c0: 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74  calls it makes t
68d0: 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e  o the xLock() an
68e0: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68  d xUnlock() meth
68f0: 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71  ods.** of an [sq
6900: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6910: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65  ] object..*/.#de
6920: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6930: 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30  _NONE          0
6940: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6950: 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20  LOCK_SHARED     
6960: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
6970: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
6980: 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  D      2.#define
6990: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e   SQLITE_LOCK_PEN
69a0: 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65  DING       3.#de
69b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
69c0: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34  _EXCLUSIVE     4
69d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
69e0: 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f  : Synchronizatio
69f0: 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a  n Type Flags.**.
6a00: 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69  ** When SQLite i
6a10: 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63  nvokes the xSync
6a20: 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a  () method of an.
6a30: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6a40: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69  ethods] object i
6a50: 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61  t uses a combina
6a60: 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65  tion of.** these
6a70: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6a80: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
6a90: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68  gument..**.** Wh
6aa0: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  en the SQLITE_SY
6ab0: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67  NC_DATAONLY flag
6ac0: 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61   is used, it mea
6ad0: 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73  ns that the.** s
6ae0: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e  ync operation on
6af0: 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73  ly needs to flus
6b00: 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73  h data to mass s
6b10: 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a  torage.  Inode.*
6b20: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65  * information ne
6b30: 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65  ed not be flushe
6b40: 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  d. If the lower 
6b50: 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65  four bits of the
6b60: 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53   flag.** equal S
6b70: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6b80: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f  L, that means to
6b90: 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   use normal fsyn
6ba0: 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a  c() semantics..*
6bb0: 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  * If the lower f
6bc0: 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53  our bits equal S
6bd0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
6be0: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
6bf0: 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73  o use Mac OS X s
6c00: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e  tyle fullsync in
6c10: 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29  stead of fsync()
6c20: 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63  ..**.** Do not c
6c30: 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54  onfuse the SQLIT
6c40: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
6c50: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
6c60: 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68  LL flags.** with
6c70: 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e   the [PRAGMA syn
6c80: 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c  chronous]=NORMAL
6c90: 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e   and [PRAGMA syn
6ca0: 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a  chronous]=FULL.*
6cb0: 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65  * settings.  The
6cc0: 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72   [synchronous pr
6cd0: 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73  agma] determines
6ce0: 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74   when calls to t
6cf0: 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20  he.** xSync VFS 
6d00: 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64  method occur and
6d10: 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d   applies uniform
6d20: 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c  ly across all pl
6d30: 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20  atforms..** The 
6d40: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
6d50: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
6d60: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65  NC_FULL flags de
6d70: 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65  termine how.** e
6d80: 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f  nergetic or rigo
6d90: 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c  rous or forceful
6da0: 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74   the sync operat
6db0: 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20  ions are and.** 
6dc0: 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66  only make a diff
6dd0: 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53  erence on Mac OS
6de0: 58 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c  X for the defaul
6df0: 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a  t SQLite code..*
6e00: 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56  * (Third-party V
6e10: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
6e20: 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61  ns might also ma
6e30: 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
6e40: 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51  on.** between SQ
6e50: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
6e60: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
6e70: 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67  _FULL, but among
6e80: 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e   the.** operatin
6e90: 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65  g systems native
6ea0: 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  ly supported by 
6eb0: 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63  SQLite, only Mac
6ec0: 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62   OSX.** cares ab
6ed0: 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e  out the differen
6ee0: 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ce.).*/.#define 
6ef0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
6f00: 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30  AL        0x0000
6f10: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
6f20: 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20  _SYNC_FULL      
6f30: 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66      0x00003.#def
6f40: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
6f50: 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78  DATAONLY      0x
6f60: 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00010../*.** CAP
6f70: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
6f80: 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61  ace Open File Ha
6f90: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73  ndle.**.** An [s
6fa0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6fb0: 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
6fc0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74  n open file in t
6fd0: 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
6fe0: 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61  vfs | OS interfa
6ff0: 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69  ce layer].  Indi
7000: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66  vidual OS interf
7010: 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ace.** implement
7020: 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77  ations will.** w
7030: 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20  ant to subclass 
7040: 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61  this object by a
7050: 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f  ppending additio
7060: 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f  nal fields.** fo
7070: 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e  r their own use.
7080: 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65    The pMethods e
7090: 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65  ntry is a pointe
70a0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
70b0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
70c0: 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
70d0: 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20  nes methods for 
70e0: 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f  performing.** I/
70f0: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20  O operations on 
7100: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a  the open file..*
7110: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
7120: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71   sqlite3_file sq
7130: 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75  lite3_file;.stru
7140: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
7150: 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74  {.  const struct
7160: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
7170: 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20  ods *pMethods;  
7180: 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61  /* Methods for a
7190: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d  n open file */.}
71a0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
71b0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
71c0: 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74  File Virtual Met
71d0: 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  hods Object.**.*
71e0: 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65  * Every file ope
71f0: 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ned by the [sqli
7200: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
7210: 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20  ethod populates 
7220: 61 6e 0a 2a 2a 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 28 6f 72 2c  ile] object (or,
7240: 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20   more commonly, 
7250: 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68  a subclass of th
7260: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
7270: 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68  le] object) with
7280: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
7290: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
72a0: 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69  s object..** Thi
72b0: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
72c0: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65   the methods use
72d0: 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  d to perform var
72e0: 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a  ious operations.
72f0: 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f  ** against the o
7300: 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65  pen file represe
7310: 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  nted by the [sql
7320: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7330: 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
7340: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7350: 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20  en] method sets 
7360: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
7370: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e  .pMethods elemen
7380: 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e  t .** to a non-N
7390: 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
73a0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f  n the sqlite3_io
73b0: 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20  _methods.xClose 
73c0: 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65  method.** may be
73d0: 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66   invoked even if
73e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
73f0: 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65  s.xOpen] reporte
7400: 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64  d that it failed
7410: 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77  .  The.** only w
7420: 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ay to prevent a 
7430: 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66  call to xClose f
7440: 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65  ollowing a faile
7450: 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  d [sqlite3_vfs.x
7460: 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20  Open].** is for 
7470: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7480: 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74  .xOpen] to set t
7490: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
74a0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
74b0: 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a  .** to NULL..**.
74c0: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
74d0: 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d  ument to xSync m
74e0: 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51  ay be one of [SQ
74f0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7500: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
7510: 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65  SYNC_FULL].  The
7520: 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73   first choice is
7530: 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   the normal fsyn
7540: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  c()..** The seco
7550: 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d  nd choice is a M
7560: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
7570: 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51  llsync.  The [SQ
7580: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
7590: 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20  LY].** flag may 
75a0: 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e  be ORed in to in
75b0: 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79  dicate that only
75c0: 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65   the data of the
75d0: 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74   file.** and not
75e0: 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73   its inode needs
75f0: 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a   to be synced..*
7600: 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72  *.** The integer
7610: 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b   values to xLock
7620: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
7630: 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c   are one of.** <
7640: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
7650: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a  ITE_LOCK_NONE],.
7660: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7670: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
7680: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7690: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a  CK_RESERVED],.**
76a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
76b0: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a  CK_PENDING], or.
76c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
76d0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e  LOCK_EXCLUSIVE].
76e0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f  .** </ul>.** xLo
76f0: 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74  ck() increases t
7700: 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b  he lock. xUnlock
7710: 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65  () decreases the
7720: 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43   lock..** The xC
7730: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
7740: 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73  () method checks
7750: 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74   whether any dat
7760: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
7770: 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74  ,.** either in t
7780: 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69  his process or i
7790: 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f  n some other pro
77a0: 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67  cess, is holding
77b0: 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20   a RESERVED,.** 
77c0: 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c  PENDING, or EXCL
77d0: 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68  USIVE lock on th
77e0: 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75  e file.  It retu
77f0: 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73  rns true.** if s
7800: 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74  uch a lock exist
7810: 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65  s and false othe
7820: 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rwise..**.** The
7830: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
7840: 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65  method is a gene
7850: 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68  ric interface th
7860: 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d  at allows custom
7870: 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  .** VFS implemen
7880: 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63  tations to direc
7890: 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f  tly control an o
78a0: 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74  pen file using t
78b0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
78c0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69  ile_control()] i
78d0: 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73  nterface.  The s
78e0: 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d  econd "op" argum
78f0: 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74  ent is an.** int
7900: 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68  eger opcode.  Th
7910: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
7920: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f   is a generic po
7930: 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74  inter intended t
7940: 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20  o.** point to a 
7950: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d  structure that m
7960: 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d  ay contain argum
7970: 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e  ents or space in
7980: 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69   which to.** wri
7990: 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73  te return values
79a0: 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65  .  Potential use
79b0: 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72  s for xFileContr
79c0: 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a  ol() might be.**
79d0: 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e   functions to en
79e0: 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f  able blocking lo
79f0: 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74  cks with timeout
7a00: 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  s, to change the
7a10: 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61  .** locking stra
7a20: 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c  tegy (for exampl
7a30: 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c  e to use dot-fil
7a40: 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71  e locks), to inq
7a50: 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68  uire.** about th
7a60: 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f  e status of a lo
7a70: 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20  ck, or to break 
7a80: 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68  stale locks.  Th
7a90: 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65  e SQLite.** core
7aa0: 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70   reserves all op
7ab0: 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20  codes less than 
7ac0: 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20  100 for its own 
7ad0: 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54  use..** A [SQLIT
7ae0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
7af0: 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f  E | list of opco
7b00: 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31  des] less than 1
7b10: 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  00 is available.
7b20: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
7b30: 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63   that define a c
7b40: 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72  ustom xFileContr
7b50: 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  ol method should
7b60: 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20   use opcodes.** 
7b70: 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30  greater than 100
7b80: 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69   to avoid confli
7b90: 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d  cts.  VFS implem
7ba0: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
7bb0: 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
7bc0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72  TE_NOTFOUND] for
7bd0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70   file control op
7be0: 63 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 20  codes that they 
7bf0: 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e  do not.** recogn
7c00: 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ize..**.** The x
7c10: 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74  SectorSize() met
7c20: 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20  hod returns the 
7c30: 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74  sector size of t
7c40: 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  he.** device tha
7c50: 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20  t underlies the 
7c60: 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f  file.  The secto
7c70: 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a  r size is the.**
7c80: 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74   minimum write t
7c90: 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f  hat can be perfo
7ca0: 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73  rmed without dis
7cb0: 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  turbing.** other
7cc0: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
7cd0: 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65  le.  The xDevice
7ce0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28  Characteristics(
7cf0: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
7d00: 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72  rns a bit vector
7d10: 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61   describing beha
7d20: 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20  viors of the.** 
7d30: 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63  underlying devic
7d40: 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
7d50: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
7d60: 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c  CAP_ATOMIC].** <
7d70: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7d80: 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20  P_ATOMIC512].** 
7d90: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7da0: 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20  AP_ATOMIC1K].** 
7db0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7dc0: 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20  AP_ATOMIC2K].** 
7dd0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7de0: 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20  AP_ATOMIC4K].** 
7df0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7e00: 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20  AP_ATOMIC8K].** 
7e10: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7e20: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a  AP_ATOMIC16K].**
7e30: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
7e40: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a  CAP_ATOMIC32K].*
7e50: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
7e60: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a  OCAP_ATOMIC64K].
7e70: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7e80: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
7e90: 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  D].** <li> [SQLI
7ea0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
7eb0: 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IAL].** </ul>.**
7ec0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
7ed0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
7ee0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
7ef0: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
7f00: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
7f10: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
7f20: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
7f30: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
7f40: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
7f50: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
7f60: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
7f70: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
7f80: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
7f90: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
7fa0: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
7fb0: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
7fc0: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
7fd0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
7fe0: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
7ff0: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
8000: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
8010: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
8020: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
8030: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
8040: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
8050: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
8060: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
8070: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
8080: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
8090: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
80a0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
80b0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
80c0: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
80d0: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
80e0: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
80f0: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a   xWrite()..**.**
8100: 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75   If xRead() retu
8110: 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  rns SQLITE_IOERR
8120: 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d  _SHORT_READ it m
8130: 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a  ust also fill.**
8140: 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70   in the unread p
8150: 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62  ortions of the b
8160: 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73  uffer with zeros
8170: 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a  .  A VFS that.**
8180: 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66   fails to zero-f
8190: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20  ill short reads 
81a0: 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f  might seem to wo
81b0: 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  rk.  However,.**
81c0: 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f   failure to zero
81d0: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
81e0: 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c  s will eventuall
81f0: 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74  y lead to.** dat
8200: 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e  abase corruption
8210: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
8220: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
8230: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69  ethods sqlite3_i
8240: 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  o_methods;.struc
8250: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
8260: 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  hods {.  int iVe
8270: 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78  rsion;.  int (*x
8280: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66  Close)(sqlite3_f
8290: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
82a0: 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69  Read)(sqlite3_fi
82b0: 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20  le*, void*, int 
82c0: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
82d0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
82e0: 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69  t (*xWrite)(sqli
82f0: 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74  te3_file*, const
8300: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
8310: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8320: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
8330: 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74  xTruncate)(sqlit
8340: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8350: 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20  3_int64 size);. 
8360: 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
8370: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8380: 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28   flags);.  int (
8390: 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69  *xFileSize)(sqli
83a0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
83b0: 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29  e3_int64 *pSize)
83c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29  ;.  int (*xLock)
83d0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
83e0: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  int);.  int (*xU
83f0: 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  nlock)(sqlite3_f
8400: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
8410: 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76  t (*xCheckReserv
8420: 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  edLock)(sqlite3_
8430: 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73  file*, int *pRes
8440: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
8450: 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69  ileControl)(sqli
8460: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
8470: 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a  p, void *pArg);.
8480: 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53    int (*xSectorS
8490: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
84a0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  e*);.  int (*xDe
84b0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
84c0: 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ics)(sqlite3_fil
84d0: 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  e*);.  /* Method
84e0: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
84f0: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20  d for version 1 
8500: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d  */.  int (*xShmM
8510: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ap)(sqlite3_file
8520: 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20  *, int iPg, int 
8530: 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20  pgsz, int, void 
8540: 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69  volatile**);.  i
8550: 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73  nt (*xShmLock)(s
8560: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8570: 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c  t offset, int n,
8580: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76   int flags);.  v
8590: 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65  oid (*xShmBarrie
85a0: 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  r)(sqlite3_file*
85b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55  );.  int (*xShmU
85c0: 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  nmap)(sqlite3_fi
85d0: 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46  le*, int deleteF
85e0: 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  lag);.  /* Metho
85f0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8600: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32  id for version 2
8610: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 74   */.  int (*xFet
8620: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
8630: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8640: 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 74   iOfst, int iAmt
8650: 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20  , void **pp);.  
8660: 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 28  int (*xUnfetch)(
8670: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8680: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8690: 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20  st, void *p);.  
86a0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
86b0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
86c0: 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a  ersion 3 */.  /*
86d0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
86e0: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
86f0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
8700: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
8710: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
8720: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
8730: 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54   Opcodes.**.** T
8740: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
8750: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
8760: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
8770: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
8780: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
8790: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
87a0: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
87b0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
87c0: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
87d0: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
87e0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
87f0: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
8800: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
8810: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
8820: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
8830: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8840: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
8850: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
8860: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
8870: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
8880: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
8890: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
88a0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
88b0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
88c0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
88d0: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
88e0: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
88f0: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8900: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8910: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8920: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8930: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8940: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8950: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
8960: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
8970: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
8980: 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  .** is defined..
8990: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b  ** <ul>.** <li>[
89a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
89b0: 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65  ZE_HINT]].** The
89c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
89d0: 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65  IZE_HINT] opcode
89e0: 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69   is used by SQLi
89f0: 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56  te to give the V
8a00: 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69  FS.** layer a hi
8a10: 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20  nt of how large 
8a20: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
8a30: 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62  e will grow to b
8a40: 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20  e during the.** 
8a50: 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
8a60: 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20  ion.  This hint 
8a70: 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  is not guarantee
8a80: 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65  d to be accurate
8a90: 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66   but it.** is of
8aa0: 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20  ten close.  The 
8ab0: 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d  underlying VFS m
8ac0: 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70  ight choose to p
8ad0: 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62  reallocate datab
8ae0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63  ase.** file spac
8af0: 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20  e based on this 
8b00: 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  hint in order to
8b10: 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20   help writes to 
8b20: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
8b30: 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e  file run faster.
8b40: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8b50: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
8b60: 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SIZE]].** The [S
8b70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
8b80: 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69  K_SIZE] opcode i
8b90: 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73  s used to reques
8ba0: 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a  t that the VFS.*
8bb0: 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72  * extends and tr
8bc0: 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61  uncates the data
8bd0: 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75  base file in chu
8be0: 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70  nks of a size sp
8bf0: 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
8c00: 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72  e user. The four
8c10: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  th argument to [
8c20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8c30: 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a  trol()] should .
8c40: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69  ** point to an i
8c50: 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74  nteger (type int
8c60: 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
8c70: 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20   new chunk-size 
8c80: 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68  to use.** for th
8c90: 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61  e nominated data
8ca0: 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67  base. Allocating
8cb0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73   database file s
8cc0: 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a  pace in large.**
8cd0: 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42   chunks (say 1MB
8ce0: 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79   at a time), may
8cf0: 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73   reduce file-sys
8d00: 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  tem fragmentatio
8d10: 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65  n and.** improve
8d20: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20   performance on 
8d30: 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a  some systems..**
8d40: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
8d50: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
8d60: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TER]].** The [SQ
8d70: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
8d80: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
8d90: 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  is used to obtai
8da0: 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  n a pointer.** t
8db0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  o the [sqlite3_f
8dc0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ile] object asso
8dd0: 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61  ciated with a pa
8de0: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
8df0: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
8e00: 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74    See the [sqlit
8e10: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8e20: 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  )] documentation
8e30: 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
8e40: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
8e50: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
8e60: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
8e70: 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65  ITTED]].** ^(The
8e80: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
8e90: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63  YNC_OMITTED] opc
8ea0: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
8eb0: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a   internally by.*
8ec0: 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65 6e  * SQLite and sen
8ed0: 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20 69  t to all VFSes i
8ee0: 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61 6c  n place of a cal
8ef0: 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20 6d  l to the xSync m
8f00: 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68  ethod.** when th
8f10: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
8f20: 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d  ction has [PRAGM
8f30: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73  A synchronous] s
8f40: 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20  et to OFF.)^.** 
8f50: 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65 64  Some specialized
8f60: 20 56 46 53 65 73 20 6e 65 65 64 20 74 68 69 73   VFSes need this
8f70: 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72   signal in order
8f80: 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 72   to operate corr
8f90: 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50  ectly.** when [P
8fa0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
8fb0: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68  s | PRAGMA synch
8fc0: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73  ronous=OFF] is s
8fd0: 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a  et, but most .**
8fe0: 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65   VFSes do not ne
8ff0: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 61  ed this signal a
9000: 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  nd should silent
9010: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
9020: 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  pcode..** Applic
9030: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
9040: 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  t call [sqlite3_
9050: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
9060: 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63  with this.** opc
9070: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
9080: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
9090: 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  operation of the
90a0: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
90b0: 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72 65  es.** that do re
90c0: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
90d0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
90e0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
90f0: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
9100: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
9110: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
9120: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
9130: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
9140: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
9150: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
9160: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
9170: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
9180: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
9190: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
91a0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
91b0: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
91c0: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
91d0: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
91e0: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
91f0: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
9200: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
9210: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
9220: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
9230: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
9240: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
9250: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
9260: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
9270: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
9280: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
9290: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
92a0: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
92b0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
92c0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
92d0: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
92e0: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
92f0: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
9300: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
9310: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
9320: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9330: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
9340: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
9350: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
9360: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
9370: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9380: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
9390: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
93a0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
93b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
93c0: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
93d0: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
93e0: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
93f0: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
9400: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
9410: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
9420: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
9430: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
9440: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
9450: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
9460: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
9470: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
9480: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
9490: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
94a0: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
94b0: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
94c0: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
94d0: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
94e0: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
94f0: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
9500: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
9510: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
9520: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9530: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9540: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
9550: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
9560: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
9570: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
9580: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
9590: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
95a0: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
95b0: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
95c0: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
95d0: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
95e0: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
95f0: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
9600: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
9610: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
9620: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
9630: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
9640: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
9650: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
9660: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
9670: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
9680: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
9690: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
96a0: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
96b0: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
96c0: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
96d0: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
96e0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
96f0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
9700: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
9710: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
9720: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
9730: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
9740: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
9750: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
9760: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
9770: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
9780: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
9790: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
97a0: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
97b0: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
97c0: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
97d0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
97e0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
97f0: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
9800: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
9810: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9820: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
9830: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
9840: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
9850: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
9860: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
9870: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
9880: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
9890: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
98a0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
98b0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
98c0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
98d0: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
98e0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
98f0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
9900: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
9910: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9920: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
9930: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
9940: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9950: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
9960: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
9970: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
9980: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
9990: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
99a0: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
99b0: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
99c0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
99d0: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
99e0: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
99f0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
9a00: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
9a10: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
9a20: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
9a30: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
9a40: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
9a50: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
9a60: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
9a70: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
9a80: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
9a90: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
9aa0: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
9ab0: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
9ac0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
9ad0: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
9ae0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
9af0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
9b00: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
9b10: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
9b20: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9b30: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
9b40: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
9b50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
9b60: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
9b70: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
9b80: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
9b90: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
9ba0: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
9bb0: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
9bc0: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
9bd0: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
9be0: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
9bf0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9c00: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
9c10: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
9c20: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
9c30: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
9c40: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
9c50: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
9c60: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9c70: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
9c80: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9c90: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
9ca0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
9cb0: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
9cc0: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
9cd0: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
9ce0: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
9cf0: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
9d00: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
9d10: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
9d20: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
9d30: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
9d40: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
9d50: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
9d60: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
9d70: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
9d80: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
9d90: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
9da0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
9db0: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
9dc0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
9dd0: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
9de0: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
9df0: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
9e00: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
9e10: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
9e20: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
9e30: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
9e40: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
9e50: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
9e60: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
9e70: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
9e80: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
9e90: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
9ea0: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
9eb0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
9ec0: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
9ed0: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
9ee0: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
9ef0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
9f00: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
9f10: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
9f20: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
9f30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
9f40: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
9f50: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
9f60: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
9f70: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
9f80: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
9f90: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
9fa0: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
9fb0: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
9fc0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
9fd0: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
9fe0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
9ff0: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
a000: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
a010: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
a020: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
a030: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a040: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
a050: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
a060: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
a070: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
a080: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
a090: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
a0a0: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
a0b0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
a0c0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
a0d0: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
a0e0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
a0f0: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
a100: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
a110: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
a120: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
a130: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
a140: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a150: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
a160: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
a170: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
a180: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
a190: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
a1a0: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
a1b0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
a1c0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
a1d0: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
a1e0: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
a1f0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
a200: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
a210: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
a220: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
a230: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
a240: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
a250: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a260: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a270: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
a280: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
a290: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
a2a0: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
a2b0: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
a2c0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
a2d0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
a2e0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
a2f0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
a300: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
a310: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
a320: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
a330: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
a340: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
a350: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
a360: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
a370: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
a380: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
a390: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a3a0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
a3b0: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73  turns.** any res
a3c0: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74  ult code other t
a3d0: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  han [SQLITE_OK] 
a3e0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  or [SQLITE_NOTFO
a3f0: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  UND], that means
a400: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53  .** that the VFS
a410: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20   encountered an 
a420: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64  error while hand
a430: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  ling the [PRAGMA
a440: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  ] and the.** com
a450: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  pilation of the 
a460: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74  PRAGMA fails wit
a470: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68  h an error.  ^Th
a480: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a490: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
a4a0: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61  control occurs a
a4b0: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  t the beginning 
a4c0: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  of pragma statem
a4d0: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64  ent analysis and
a4e0: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c   so.** it is abl
a4f0: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75  e to override bu
a500: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20  ilt-in [PRAGMA] 
a510: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
a520: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a530: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
a540: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
a550: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
a560: 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f  DLER].** file-co
a570: 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76  ntrol may be inv
a580: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f  oked by SQLite o
a590: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
a5a0: 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68  ile handle.** sh
a5b0: 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69  ortly after it i
a5c0: 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65  s opened in orde
a5d0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63  r to provide a c
a5e0: 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61  ustom VFS with a
a5f0: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20  ccess.** to the 
a600: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79  connections busy
a610: 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
a620: 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  k. The argument 
a630: 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  is of type (void
a640: 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72   **).** - an arr
a650: 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20  ay of two (void 
a660: 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66  *) values. The f
a670: 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63  irst (void *) ac
a680: 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a  tually points.**
a690: 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
a6a0: 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28  f type (int (*)(
a6b0: 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64  void *)). In ord
a6c0: 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  er to invoke the
a6d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
a6e0: 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68  busy-handler, th
a6f0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  is function shou
a700: 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ld be invoked wi
a710: 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76  th the second (v
a720: 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65  oid *) in.** the
a730: 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e   array as the on
a740: 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20  ly argument. If 
a750: 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  it returns non-z
a760: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70  ero, then the op
a770: 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  eration.** shoul
a780: 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66  d be retried. If
a790: 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f   it returns zero
a7a0: 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53  , the custom VFS
a7b0: 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20   should abandon 
a7c0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f  the.** current o
a7d0: 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  peration..**.** 
a7e0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
a7f0: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
a800: 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f  ].** ^Applicatio
a810: 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65  n can invoke the
a820: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
a830: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c  EMPFILENAME] fil
a840: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20  e-control.** to 
a850: 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65  have SQLite gene
a860: 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72  rate a.** tempor
a870: 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69  ary filename usi
a880: 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
a890: 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f  rithm that is fo
a8a0: 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61  llowed to genera
a8b0: 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
a8c0: 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45  filenames for TE
a8d0: 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74  MP tables and ot
a8e0: 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65  her internal use
a8f0: 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d  s.  The.** argum
a900: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ent should be a 
a910: 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c  char** which wil
a920: 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68  l be filled with
a930: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
a940: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
a950: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
a960: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
a970: 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c  oc()].  The call
a980: 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76  er should.** inv
a990: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
a9a0: 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75  e()] on the resu
a9b0: 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65  lt to avoid a me
a9c0: 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a  mory leak..**.**
a9d0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a9e0: 4e 54 4c 5f 4d 4d 41 50 5f 4c 49 4d 49 54 5d 5d  NTL_MMAP_LIMIT]]
a9f0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
aa00: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 4c 49 4d 49 54  FCNTL_MMAP_LIMIT
aa10: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
aa20: 73 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20  s used to query 
aa30: 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61  or set the.** ma
aa40: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
aa50: 62 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20  bytes that will 
aa60: 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f  be used for memo
aa70: 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a  ry-mapped I/O..*
aa80: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  * The argument i
aa90: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
aaa0: 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73   value of type s
aab0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61  qlite3_int64 tha
aac0: 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73  t.** is an advis
aad0: 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ory maximum numb
aae0: 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
aaf0: 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72  he file to memor
ab00: 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70  y map.  The.** p
ab10: 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72  ointer is overwr
ab20: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f  itten with the o
ab30: 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c  ld value.  The l
ab40: 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e  imit is not chan
ab50: 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 6f 72  ged if.** the or
ab60: 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64  iginally pointed
ab70: 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c   to is negative,
ab80: 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72   and so the curr
ab90: 65 6e 74 20 6c 69 6d 69 74 20 63 61 6e 20 62 65  ent limit can be
aba0: 0a 2a 2a 20 71 75 65 72 69 65 64 20 62 79 20 70  .** queried by p
abb0: 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e  assing in a poin
abc0: 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76  ter to a negativ
abd0: 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 20  e number.  This 
abe0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
abf0: 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
ac00: 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ly to implement 
ac10: 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 6c 69 6d  [PRAGMA mmap_lim
ac20: 69 74 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e  it]..**.** </ul>
ac30: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
ac40: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
ac50: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
ac60: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
ac70: 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_GET_LOCKPROXYF
ac80: 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ILE             
ac90: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
aca0: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
acb0: 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 33  LE             3
acc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
acd0: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
ace0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a                4.
acf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
ad00: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20  CNTL_SIZE_HINT  
ad10: 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
ad20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ad30: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20  NTL_CHUNK_SIZE  
ad40: 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
ad50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ad60: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20  TL_FILE_POINTER 
ad70: 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
ad80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ad90: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20  L_SYNC_OMITTED  
ada0: 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66            8.#def
adb0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
adc0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20  _WIN32_AV_RETRY 
add0: 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
ade0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
adf0: 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20  PERSIST_WAL     
ae00: 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e         10.#defin
ae10: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  e SQLITE_FCNTL_O
ae20: 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20  VERWRITE        
ae30: 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65        11.#define
ae40: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46   SQLITE_FCNTL_VF
ae50: 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  SNAME           
ae60: 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20       12.#define 
ae70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
ae80: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
ae90: 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53      13.#define S
aea0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
aeb0: 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
aec0: 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51     14.#define SQ
aed0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
aee0: 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20  ANDLER          
aef0: 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c    15.#define SQL
af00: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
af10: 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  LENAME          
af20: 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   16.#define SQLI
af30: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 4c 49  TE_FCNTL_MMAP_LI
af40: 4d 49 54 20 20 20 20 20 20 20 20 20 20 20 20 20  MIT             
af50: 31 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  18../*.** CAPI3R
af60: 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65  EF: Mutex Handle
af70: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78  .**.** The mutex
af80: 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53   module within S
af90: 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73  QLite defines [s
afa0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f  qlite3_mutex] to
afb0: 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61   be an.** abstra
afc0: 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75  ct type for a mu
afd0: 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  tex object.  The
afe0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76   SQLite core nev
aff0: 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74  er looks.** at t
b000: 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
b010: 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  esentation of an
b020: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
b030: 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65  .  It only.** de
b040: 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72  als with pointer
b050: 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
b060: 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e  3_mutex] object.
b070: 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61  .**.** Mutexes a
b080: 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  re created using
b090: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
b0a0: 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70  alloc()]..*/.typ
b0b0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
b0c0: 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65  te3_mutex sqlite
b0d0: 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20  3_mutex;../*.** 
b0e0: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
b0f0: 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a  erface Object.**
b100: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
b110: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
b120: 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  fs object define
b130: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
b140: 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53  between.** the S
b150: 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74  QLite core and t
b160: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70  he underlying op
b170: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
b180: 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e   The "vfs".** in
b190: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
b1a0: 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66   object stands f
b1b0: 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65  or "virtual file
b1c0: 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a   system".  See.*
b1d0: 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53  * the [VFS | VFS
b1e0: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
b1f0: 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f  for further info
b200: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
b210: 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
b220: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69  iVersion field i
b230: 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75  s initially 1 bu
b240: 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20  t may be larger 
b250: 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72  in.** future ver
b260: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
b270: 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65    Additional fie
b280: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
b290: 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f  ded to this.** o
b2a0: 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69  bject when the i
b2b0: 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73  Version value is
b2c0: 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74   increased.  Not
b2d0: 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63  e that the struc
b2e0: 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73  ture.** of the s
b2f0: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
b300: 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  t changes in the
b310: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74   transaction bet
b320: 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76  ween.** SQLite v
b330: 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64  ersion 3.5.9 and
b340: 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74   3.6.0 and yet t
b350: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
b360: 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64  d was not.** mod
b370: 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ified..**.** The
b380: 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20   szOsFile field 
b390: 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
b3a0: 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73  he subclassed [s
b3b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20  qlite3_file].** 
b3c0: 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62  structure used b
b3d0: 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50  y this VFS.  mxP
b3e0: 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d  athname is the m
b3f0: 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
b400: 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69  .** a pathname i
b410: 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a  n this VFS..**.*
b420: 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c  * Registered sql
b430: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73  ite3_vfs objects
b440: 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c   are kept on a l
b450: 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65  inked list forme
b460: 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78  d by.** the pNex
b470: 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  t pointer.  The 
b480: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67  [sqlite3_vfs_reg
b490: 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20  ister()].** and 
b4a0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72  [sqlite3_vfs_unr
b4b0: 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72  egister()] inter
b4c0: 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69  faces manage thi
b4d0: 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74  s list.** in a t
b4e0: 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20  hread-safe way. 
b4f0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
b500: 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66  s_find()] interf
b510: 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20  ace.** searches 
b520: 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68  the list.  Neith
b530: 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
b540: 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20  on code nor the 
b550: 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  VFS.** implement
b560: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ation should use
b570: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
b580: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e  er..**.** The pN
b590: 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65  ext field is the
b5a0: 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74   only field in t
b5b0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
b5c0: 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74  * structure that
b5d0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65   SQLite will eve
b5e0: 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74  r modify.  SQLit
b5f0: 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65  e will only acce
b600: 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20  ss.** or modify 
b610: 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65  this field while
b620: 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69   holding a parti
b630: 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74  cular static mut
b640: 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ex..** The appli
b650: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
b660: 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68  ver modify anyth
b670: 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73  ing within the s
b680: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62  qlite3_vfs.** ob
b690: 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62  ject once the ob
b6a0: 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65  ject has been re
b6b0: 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  gistered..**.** 
b6c0: 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20  The zName field 
b6d0: 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f  holds the name o
b6e0: 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65  f the VFS module
b6f0: 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74  .  The name must
b700: 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63  .** be unique ac
b710: 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64  ross all VFS mod
b720: 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  ules..**.** [[sq
b730: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
b740: 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61  ].** ^SQLite gua
b750: 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
b760: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
b770: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a  eter to xOpen.**
b780: 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c   is either a NUL
b790: 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72  L pointer or str
b7a0: 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ing obtained.** 
b7b0: 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61  from xFullPathna
b7c0: 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74  me() with an opt
b7d0: 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64  ional suffix add
b7e0: 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66  ed..** ^If a suf
b7f0: 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20  fix is added to 
b800: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
b810: 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c  rameter, it will
b820: 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61  .** consist of a
b830: 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72   single "-" char
b840: 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62  acter followed b
b850: 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a  y no more than.*
b860: 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69  * 11 alphanumeri
b870: 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61  c and/or "-" cha
b880: 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c  racters..** ^SQL
b890: 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72  ite further guar
b8a0: 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74  antees that.** t
b8b0: 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
b8c0: 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68  e valid and unch
b8d0: 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f  anged until xClo
b8e0: 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65  se() is.** calle
b8f0: 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  d. Because of th
b900: 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
b910: 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  nce,.** the [sql
b920: 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73  ite3_file] can s
b930: 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f  afely store a po
b940: 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  inter to the.** 
b950: 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e  filename if it n
b960: 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72  eeds to remember
b970: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f   the filename fo
b980: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a  r some reason..*
b990: 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61  * If the zFilena
b9a0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
b9b0: 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20  xOpen is a NULL 
b9c0: 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70  pointer then xOp
b9d0: 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e  en.** must inven
b9e0: 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72  t its own tempor
b9f0: 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65  ary name for the
ba00: 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65   file.  ^Wheneve
ba10: 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e  r the .** xFilen
ba20: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
ba30: 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c   NULL it will al
ba40: 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74  so be the case t
ba50: 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73  hat the.** flags
ba60: 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20   parameter will 
ba70: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
ba80: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
ba90: 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  SE]..**.** The f
baa0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
bab0: 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65   xOpen() include
bac0: 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69  s all bits set i
bad0: 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61  n.** the flags a
bae0: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
baf0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
bb00: 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   Or if [sqlite3_
bb10: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  open()].** or [s
bb20: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
bb30: 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66   is used, then f
bb40: 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74  lags includes at
bb50: 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54   least.** [SQLIT
bb60: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
bb70: 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
bb80: 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66  _CREATE]. .** If
bb90: 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61   xOpen() opens a
bba0: 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20   file read-only 
bbb0: 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f  then it sets *pO
bbc0: 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e  utFlags to.** in
bbd0: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
bbe0: 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f  EN_READONLY].  O
bbf0: 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f  ther bits in *pO
bc00: 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73  utFlags may be s
bc10: 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69  et..**.** ^(SQLi
bc20: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64  te will also add
bc30: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
bc40: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
bc50: 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61  he xOpen().** ca
bc60: 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ll, depending on
bc70: 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e   the object bein
bc80: 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20  g opened:.**.** 
bc90: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  <ul>.** <li>  [S
bca0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
bcb0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
bcc0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
bcd0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
bce0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
bcf0: 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  MP_DB].** <li>  
bd00: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
bd10: 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  P_JOURNAL].** <l
bd20: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
bd30: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a  _TRANSIENT_DB].*
bd40: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
bd50: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d  OPEN_SUBJOURNAL]
bd60: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
bd70: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
bd80: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
bd90: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c  [SQLITE_OPEN_WAL
bda0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  ].** </ul>)^.**.
bdb0: 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20  ** The file I/O 
bdc0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63  implementation c
bdd0: 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63  an use the objec
bde0: 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a  t type flags to.
bdf0: 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61  ** change the wa
be00: 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20  y it deals with 
be10: 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d  files.  For exam
be20: 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
be30: 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73  ion.** that does
be40: 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20   not care about 
be50: 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f  crash recovery o
be60: 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74  r rollback might
be70: 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65   make.** the ope
be80: 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66  n of a journal f
be90: 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72  ile a no-op.  Wr
bea0: 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75  ites to this jou
beb0: 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c  rnal would.** al
bec0: 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e  so be no-ops, an
bed0: 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  d any attempt to
bee0: 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61   read the journa
bef0: 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a  l would return.*
bf00: 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20  * SQLITE_IOERR. 
bf10: 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e   Or the implemen
bf20: 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63  tation might rec
bf30: 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61  ognize that a da
bf40: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77  tabase.** file w
bf50: 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67  ill be doing pag
bf60: 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72  e-aligned sector
bf70: 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65   reads and write
bf80: 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a  s in a random.**
bf90: 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75   order and set u
bfa0: 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73  p its I/O subsys
bfb0: 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e  tem accordingly.
bfc0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69  .**.** SQLite mi
bfd0: 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ght also add one
bfe0: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
bff0: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
c000: 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Open method:.**.
c010: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
c020: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
c030: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c  ETEONCLOSE].** <
c040: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
c050: 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c  _EXCLUSIVE].** <
c060: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  /ul>.**.** The [
c070: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
c080: 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20  TEONCLOSE] flag 
c090: 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73  means the file s
c0a0: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65  hould be.** dele
c0b0: 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63  ted when it is c
c0c0: 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51  losed.  ^The [SQ
c0d0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
c0e0: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c  ONCLOSE].** will
c0f0: 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50   be set for TEMP
c100: 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74   databases and t
c110: 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74  heir journals, t
c120: 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61  ransient.** data
c130: 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f  bases, and subjo
c140: 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  urnals..**.** ^T
c150: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
c160: 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20  EXCLUSIVE] flag 
c170: 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69  is always used i
c180: 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a  n conjunction.**
c190: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
c1a0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66  E_OPEN_CREATE] f
c1b0: 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62  lag, which are b
c1c0: 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  oth directly.** 
c1d0: 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65  analogous to the
c1e0: 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52   O_EXCL and O_CR
c1f0: 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65  EAT flags of the
c200: 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a   POSIX open().**
c210: 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54   API.  The SQLIT
c220: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
c230: 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72   flag, when pair
c240: 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
c250: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
c260: 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69  TE, is used to i
c270: 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c  ndicate that fil
c280: 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a  e should always.
c290: 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61  ** be created, a
c2a0: 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e  nd that it is an
c2b0: 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72   error if it alr
c2c0: 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20  eady exists..** 
c2d0: 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e  It is <i>not</i>
c2e0: 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
c2f0: 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  e the file shoul
c300: 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20  d be opened .** 
c310: 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63  for exclusive ac
c320: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20  cess..**.** ^At 
c330: 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62  least szOsFile b
c340: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61  ytes of memory a
c350: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
c360: 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c  SQLite.** to hol
c370: 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f  d the  [sqlite3_
c380: 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20  file] structure 
c390: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
c3a0: 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ird.** argument 
c3b0: 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78  to xOpen.  The x
c3c0: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73  Open method does
c3d0: 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20   not have to.** 
c3e0: 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72  allocate the str
c3f0: 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c  ucture; it shoul
c400: 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69  d just fill it i
c410: 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a  n.  Note that.**
c420: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
c430: 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73  d must set the s
c440: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
c450: 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a  hods to either.*
c460: 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74  * a valid [sqlit
c470: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
c480: 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c  bject or to NULL
c490: 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f  .  xOpen must do
c4a0: 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66  .** this even if
c4b0: 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e   the open fails.
c4c0: 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73    SQLite expects
c4d0: 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65   that the sqlite
c4e0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a  3_file.pMethods.
c4f0: 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20  ** element will 
c500: 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78  be valid after x
c510: 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67  Open returns reg
c520: 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73  ardless of the s
c530: 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69  uccess.** or fai
c540: 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65  lure of the xOpe
c550: 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  n call..**.** [[
c560: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63  sqlite3_vfs.xAcc
c570: 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c  ess]].** ^The fl
c580: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
c590: 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65  xAccess() may be
c5a0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
c5b0: 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65  EXISTS].** to te
c5c0: 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74  st for the exist
c5d0: 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20  ence of a file, 
c5e0: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
c5f0: 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a  S_READWRITE] to.
c600: 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20  ** test whether 
c610: 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  a file is readab
c620: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c  le and writable,
c630: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
c640: 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74  SS_READ].** to t
c650: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
c660: 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72  le is at least r
c670: 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66  eadable.   The f
c680: 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20  ile can be a.** 
c690: 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
c6a0: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c   ^SQLite will al
c6b0: 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74  ways allocate at
c6c0: 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d   least mxPathnam
c6d0: 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68  e+1 bytes for th
c6e0: 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66  e.** output buff
c6f0: 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  er xFullPathname
c700: 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a  .  The exact siz
c710: 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20  e of the output 
c720: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73  buffer.** is als
c730: 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61  o passed as a pa
c740: 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20  rameter to both 
c750: 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65   methods. If the
c760: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
c770: 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65  * is not large e
c780: 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43  nough, [SQLITE_C
c790: 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20  ANTOPEN] should 
c7a0: 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e  be returned. Sin
c7b0: 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61  ce this is.** ha
c7c0: 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c  ndled as a fatal
c7d0: 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65   error by SQLite
c7e0: 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61  , vfs implementa
c7f0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64  tions should end
c800: 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76  eavor.** to prev
c810: 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74  ent this by sett
c820: 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74  ing mxPathname t
c830: 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79  o a sufficiently
c840: 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a   large value..**
c850: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
c860: 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c  ess(), xSleep(),
c870: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c   xCurrentTime(),
c880: 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d   and xCurrentTim
c890: 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65  eInt64().** inte
c8a0: 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73  rfaces are not s
c8b0: 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f  trictly a part o
c8c0: 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d  f the filesystem
c8d0: 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a  , but they are.*
c8e0: 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  * included in th
c8f0: 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20  e VFS structure 
c900: 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73  for completeness
c910: 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  ..** The xRandom
c920: 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  ness() function 
c930: 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75  attempts to retu
c940: 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a  rn nBytes bytes.
c950: 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69  ** of good-quali
c960: 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  ty randomness in
c970: 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65  to zOut.  The re
c980: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a  turn value is.**
c990: 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62   the actual numb
c9a0: 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72  er of bytes of r
c9b0: 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
c9c0: 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65  ed..** The xSlee
c9d0: 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65  p() method cause
c9e0: 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68  s the calling th
c9f0: 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f  read to sleep fo
ca00: 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68  r at.** least th
ca10: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72  e number of micr
ca20: 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20  oseconds given. 
ca30: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
ca40: 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  me().** method r
ca50: 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20  eturns a Julian 
ca60: 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74  Day Number for t
ca70: 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20  he current date 
ca80: 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61  and time as.** a
ca90: 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
caa0: 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78  value..** ^The x
cab0: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
cac0: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
cad0: 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72  s, as an integer
cae0: 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20  , the Julian.** 
caf0: 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69  Day Number multi
cb00: 70 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30  plied by 8640000
cb10: 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  0 (the number of
cb20: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e   milliseconds in
cb30: 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64   .** a 24-hour d
cb40: 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74  ay).  .** ^SQLit
cb50: 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78  e will use the x
cb60: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
cb70: 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74  () method to get
cb80: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
cb90: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66  date and time if
cba0: 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20   that method is 
cbb0: 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56  available (if iV
cbc0: 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a  ersion is 2 or .
cbd0: 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74  ** greater and t
cbe0: 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  he function poin
cbf0: 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29  ter is not NULL)
cc00: 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62   and will fall b
cc10: 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65  ack.** to xCurre
cc20: 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72  ntTime() if xCur
cc30: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
cc40: 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
cc50: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53  **.** ^The xSetS
cc60: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65  ystemCall(), xGe
cc70: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61  tSystemCall(), a
cc80: 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61  nd xNestSystemCa
cc90: 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  ll() interfaces.
cca0: 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20  ** are not used 
ccb0: 62 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  by the SQLite co
ccc0: 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f  re.  These optio
ccd0: 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  nal interfaces a
cce0: 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62  re provided.** b
ccf0: 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20  y some VFSes to 
cd00: 66 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69  facilitate testi
cd10: 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f  ng of the VFS co
cd20: 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e  de. By overridin
cd30: 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c  g .** system cal
cd40: 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e  ls with function
cd50: 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74  s under its cont
cd60: 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67  rol, a test prog
cd70: 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c  ram can.** simul
cd80: 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65  ate faults and e
cd90: 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20  rror conditions 
cda0: 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72  that would other
cdb0: 77 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c  wise be difficul
cdc0: 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62  t.** or impossib
cdd0: 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54  le to induce.  T
cde0: 68 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d  he set of system
cdf0: 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20   calls that can 
ce00: 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a  be overridden.**
ce10: 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65   varies from one
ce20: 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c   VFS to another,
ce30: 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65   and from one ve
ce40: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d  rsion of the sam
ce50: 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20  e VFS to the.** 
ce60: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
ce70: 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65  ons that use the
ce80: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75  se interfaces mu
ce90: 73 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66  st be prepared f
cea0: 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c  or any.** or all
ceb0: 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66   of these interf
cec0: 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20  aces to be NULL 
ced0: 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68  or for their beh
cee0: 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a  avior to change.
cef0: 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65  ** from one rele
cf00: 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ase to the next.
cf10: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d    Applications m
cf20: 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20  ust not attempt 
cf30: 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79  to access.** any
cf40: 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64   of these method
cf50: 73 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f  s if the iVersio
cf60: 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20  n of the VFS is 
cf70: 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a  less than 3..*/.
cf80: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
cf90: 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74  qlite3_vfs sqlit
cfa0: 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20  e3_vfs;.typedef 
cfb0: 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73  void (*sqlite3_s
cfc0: 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64  yscall_ptr)(void
cfd0: 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  );.struct sqlite
cfe0: 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56  3_vfs {.  int iV
cff0: 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20  ersion;         
d000: 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20     /* Structure 
d010: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28  version number (
d020: 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a  currently 3) */.
d030: 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20    int szOsFile; 
d040: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69             /* Si
d050: 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64  ze of subclassed
d060: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f   sqlite3_file */
d070: 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d  .  int mxPathnam
d080: 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  e;          /* M
d090: 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68  aximum file path
d0a0: 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20  name length */. 
d0b0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e   sqlite3_vfs *pN
d0c0: 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78  ext;      /* Nex
d0d0: 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53  t registered VFS
d0e0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
d0f0: 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f   *zName;       /
d100: 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76  * Name of this v
d110: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
d120: 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  em */.  void *pA
d130: 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
d140: 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61   /* Pointer to a
d150: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69  pplication-speci
d160: 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e  fic data */.  in
d170: 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
d180: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
d190: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
d1a0: 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20  te3_file*,.     
d1b0: 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c            int fl
d1c0: 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c  ags, int *pOutFl
d1d0: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  ags);.  int (*xD
d1e0: 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76  elete)(sqlite3_v
d1f0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
d200: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63  *zName, int sync
d210: 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41  Dir);.  int (*xA
d220: 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  ccess)(sqlite3_v
d230: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
d240: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67  *zName, int flag
d250: 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  s, int *pResOut)
d260: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50  ;.  int (*xFullP
d270: 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  athname)(sqlite3
d280: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
d290: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f  r *zName, int nO
d2a0: 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  ut, char *zOut);
d2b0: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70  .  void *(*xDlOp
d2c0: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
d2d0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  , const char *zF
d2e0: 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64  ilename);.  void
d2f0: 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c   (*xDlError)(sql
d300: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
d310: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72  Byte, char *zErr
d320: 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28  Msg);.  void (*(
d330: 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33  *xDlSym)(sqlite3
d340: 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e  _vfs*,void*, con
d350: 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c  st char *zSymbol
d360: 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64  ))(void);.  void
d370: 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c   (*xDlClose)(sql
d380: 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a  ite3_vfs*, void*
d390: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64  );.  int (*xRand
d3a0: 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f  omness)(sqlite3_
d3b0: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
d3c0: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
d3d0: 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71  int (*xSleep)(sq
d3e0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
d3f0: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20  microseconds);. 
d400: 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54   int (*xCurrentT
d410: 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ime)(sqlite3_vfs
d420: 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69  *, double*);.  i
d430: 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72  nt (*xGetLastErr
d440: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
d450: 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a  , int, char *);.
d460: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
d470: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
d480: 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20  in version 1 of 
d490: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
d4a0: 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e  bject.  ** defin
d4b0: 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68  ition.  Those th
d4c0: 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64  at follow are ad
d4d0: 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32  ded in version 2
d4e0: 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20   or later.  */. 
d4f0: 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54   int (*xCurrentT
d500: 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65  imeInt64)(sqlite
d510: 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f  3_vfs*, sqlite3_
d520: 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20  int64*);.  /*.  
d530: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
d540: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
d550: 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20  ions 1 and 2 of 
d560: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
d570: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73  bject..  ** Thos
d580: 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20  e below are for 
d590: 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72  version 3 and gr
d5a0: 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e  eater..  */.  in
d5b0: 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61  t (*xSetSystemCa
d5c0: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
d5d0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
d5e0: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73  ame, sqlite3_sys
d5f0: 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c  call_ptr);.  sql
d600: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
d610: 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c   (*xGetSystemCal
d620: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
d630: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
d640: 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61  me);.  const cha
d650: 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d  r *(*xNextSystem
d660: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
d670: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
d680: 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a  zName);.  /*.  *
d690: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
d6a0: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
d6b0: 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20  ons 1 through 3 
d6c0: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
d6d0: 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e  s object..  ** N
d6e0: 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  ew fields may be
d6f0: 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67   appended in fig
d700: 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54  ure versions.  T
d710: 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a  he iVersion.  **
d720: 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72   value will incr
d730: 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74  ement whenever t
d740: 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20  his happens. .  
d750: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
d760: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
d770: 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53   the xAccess VFS
d780: 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68   method.**.** Th
d790: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
d7a0: 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65  tants can be use
d7b0: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70  d as the third p
d7c0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
d7d0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
d7e0: 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  d of an [sqlite3
d7f0: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54  _vfs] object.  T
d800: 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a  hey determine.**
d810: 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65   what kind of pe
d820: 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41  rmissions the xA
d830: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20  ccess method is 
d840: 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20  looking for..** 
d850: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
d860: 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78  SS_EXISTS, the x
d870: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
d880: 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77   simply checks w
d890: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
d8a0: 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20  exists..** With 
d8b0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
d8c0: 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63  ADWRITE, the xAc
d8d0: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63  cess method.** c
d8e0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
d8f0: 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72  e named director
d900: 79 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62  y is both readab
d910: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a  le and writable.
d920: 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72  ** (in other wor
d930: 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e  ds, if files can
d940: 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76   be added, remov
d950: 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20  ed, and renamed 
d960: 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69  within.** the di
d970: 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65  rectory)..** The
d980: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
d990: 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e  EADWRITE constan
d9a0: 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75  t is currently u
d9b0: 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a  sed only by the.
d9c0: 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  ** [temp_store_d
d9d0: 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
d9e0: 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f  , though this co
d9f0: 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20  uld change in a 
da00: 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73  future.** releas
da10: 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  e of SQLite..** 
da20: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
da30: 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63  SS_READ, the xAc
da40: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63  cess method.** c
da50: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
da60: 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  e file is readab
da70: 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  le.  The SQLITE_
da80: 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73  ACCESS_READ cons
da90: 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65  tant is.** curre
daa0: 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f  ntly unused, tho
dab0: 75 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20  ugh it might be 
dac0: 75 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65  used in a future
dad0: 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53   release of.** S
dae0: 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
daf0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
db00: 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66  EXISTS    0.#def
db10: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
db20: 53 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20  S_READWRITE 1   
db30: 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d  /* Used by PRAGM
db40: 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72  A temp_store_dir
db50: 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e  ectory */.#defin
db60: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
db70: 52 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a  READ      2   /*
db80: 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a   Unused */../*.*
db90: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
dba0: 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f  s for the xShmLo
dbb0: 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ck VFS method.**
dbc0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
dbd0: 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  r constants defi
dbe0: 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  ne the various l
dbf0: 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e  ocking operation
dc00: 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20  s.** allowed by 
dc10: 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  the xShmLock met
dc20: 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  hod of [sqlite3_
dc30: 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68  io_methods].  Th
dc40: 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  e.** following a
dc50: 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61  re the only lega
dc60: 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f  l combinations o
dc70: 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a  f flags to the.*
dc80: 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  * xShmLock metho
dc90: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
dca0: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
dcb0: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
dcc0: 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c  SHM_SHARED.** <l
dcd0: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
dce0: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
dcf0: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c  _EXCLUSIVE.** <l
dd00: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  i>  SQLITE_SHM_U
dd10: 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  NLOCK | SQLITE_S
dd20: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
dd30: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
dd40: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
dd50: 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c  M_EXCLUSIVE.** <
dd60: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  /ul>.**.** When 
dd70: 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73  unlocking, the s
dd80: 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58  ame SHARED or EX
dd90: 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73  CLUSIVE flag mus
dda0: 74 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73  t be supplied as
ddb0: 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f  .** was given no
ddc0: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
ddd0: 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a  ng lock.  .**.**
dde0: 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
ddf0: 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74  thod can transit
de00: 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  ion between unlo
de10: 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20  cked and SHARED 
de20: 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e  or.** between un
de30: 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55  locked and EXCLU
de40: 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74  SIVE.  It cannot
de50: 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77   transition betw
de60: 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e  een SHARED.** an
de70: 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a  d EXCLUSIVE..*/.
de80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
de90: 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  HM_UNLOCK       
dea0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
deb0: 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20  _SHM_LOCK       
dec0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
ded0: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20  TE_SHM_SHARED   
dee0: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
def0: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
df00: 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43  VE    8../*.** C
df10: 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d  API3REF: Maximum
df20: 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a   xShmLock index.
df30: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
df40: 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71  ck method on [sq
df50: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
df60: 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73  ] may use values
df70: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
df80: 64 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75  d this upper bou
df90: 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65  nd as its "offse
dfa0: 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  t" argument..** 
dfb0: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
dfc0: 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d  will never attem
dfd0: 70 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72  pt to acquire or
dfe0: 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f   release a.** lo
dff0: 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  ck outside of th
e000: 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66  is range.*/.#def
e010: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e  ine SQLITE_SHM_N
e020: 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a  LOCK        8...
e030: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
e040: 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53  Initialize The S
e050: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
e060: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
e070: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
e080: 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65  utine initialize
e090: 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  s the.** SQLite 
e0a0: 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73  library.  ^The s
e0b0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
e0c0: 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61  ) routine.** dea
e0d0: 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73  llocates any res
e0e0: 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65  ources that were
e0f0: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
e100: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
e110: 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ()..** These rou
e120: 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e  tines are design
e130: 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f  ed to aid in pro
e140: 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
e150: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64  ion and.** shutd
e160: 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20  own on embedded 
e170: 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74  systems.  Workst
e180: 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f  ation applicatio
e190: 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69  ns using.** SQLi
e1a0: 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e  te normally do n
e1b0: 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b  ot need to invok
e1c0: 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73  e either of thes
e1d0: 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
e1e0: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
e1f0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
e200: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
e210: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
e220: 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69  .** the first ti
e230: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
e240: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
e250: 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69  ed during the li
e260: 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65  fetime of.** the
e270: 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20   process, or if 
e280: 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  it is the first 
e290: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
e2a0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
e2b0: 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  oked.** followin
e2c0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  g a call to sqli
e2d0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
e2e0: 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63   ^(Only an effec
e2f0: 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20  tive call.** of 
e300: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e310: 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e  ze() does any in
e320: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41  itialization.  A
e330: 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a  ll other calls.*
e340: 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  * are harmless n
e350: 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41  o-ops.)^.**.** A
e360: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
e370: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61  _shutdown() is a
e380: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
e390: 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20  ll if it is the 
e3a0: 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f  first.** call to
e3b0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
e3c0: 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61  n() since the la
e3d0: 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  st sqlite3_initi
e3e0: 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79  alize().  ^(Only
e3f0: 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65  .** an effective
e400: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
e410: 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73  _shutdown() does
e420: 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a   any deinitializ
e430: 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74  ation..** All ot
e440: 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20  her valid calls 
e450: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
e460: 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65  own() are harmle
e470: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
e480: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
e490: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65  nitialize() inte
e4a0: 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73  rface is threads
e4b0: 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33  afe, but sqlite3
e4c0: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69  _shutdown().** i
e4d0: 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69  s not.  The sqli
e4e0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
e4f0: 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e  nterface must on
e500: 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  ly be called fro
e510: 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68  m a.** single th
e520: 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20  read.  All open 
e530: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
e540: 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63  tions] must be c
e550: 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a  losed and all.**
e560: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65   other SQLite re
e570: 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20  sources must be 
e580: 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f  deallocated prio
e590: 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a  r to invoking.**
e5a0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
e5b0: 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67  n()..**.** Among
e5c0: 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e   other things, ^
e5d0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e5e0: 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ze() will invoke
e5f0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  .** sqlite3_os_i
e600: 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c  nit().  Similarl
e610: 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74  y, ^sqlite3_shut
e620: 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69  down().** will i
e630: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73  nvoke sqlite3_os
e640: 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  _end()..**.** ^T
e650: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
e660: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
e670: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
e680: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a  OK] on success..
e690: 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20  ** ^If for some 
e6a0: 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  reason, sqlite3_
e6b0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
e6c0: 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61  unable to initia
e6d0: 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72  lize.** the libr
e6e0: 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20  ary (perhaps it 
e6f0: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
e700: 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72  ocate a needed r
e710: 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20  esource such.** 
e720: 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72  as a mutex) it r
e730: 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72  eturns an [error
e740: 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61   code] other tha
e750: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  n [SQLITE_OK]..*
e760: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
e770: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
e780: 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
e790: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d   internally by m
e7a0: 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  any other.** SQL
e7b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73  ite interfaces s
e7c0: 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63  o that an applic
e7d0: 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f  ation usually do
e7e0: 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a  es not need to.*
e7f0: 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
e800: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
e810: 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61  rectly.  For exa
e820: 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  mple, [sqlite3_o
e830: 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20  pen()].** calls 
e840: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e850: 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69  ze() so the SQLi
e860: 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20  te library will 
e870: 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
e880: 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  .** initialized 
e890: 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70  when [sqlite3_op
e8a0: 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  en()] is called 
e8b0: 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65  if it has not be
e8c0: 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20   initialized.** 
e8d0: 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76  already.  ^Howev
e8e0: 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73  er, if SQLite is
e8f0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
e900: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
e910: 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d  AUTOINIT].** com
e920: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
e930: 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d  , then the autom
e940: 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71  atic calls to sq
e950: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
e960: 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65  ().** are omitte
e970: 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  d and the applic
e980: 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20  ation must call 
e990: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e9a0: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a  ze() directly.**
e9b0: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
e9c0: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
e9d0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72   interface.  For
e9e0: 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69   maximum portabi
e9f0: 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72  lity,.** it is r
ea00: 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
ea10: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77  applications alw
ea20: 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ays invoke sqlit
ea30: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
ea40: 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f  ** directly prio
ea50: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
ea60: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
ea70: 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72  rface.  Future r
ea80: 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51  eleases.** of SQ
ea90: 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65  Lite may require
eaa0: 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72   this.  In other
eab0: 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61   words, the beha
eac0: 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a  vior exhibited.*
ead0: 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  * when SQLite is
eae0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
eaf0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
eb00: 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f  INIT] might beco
eb10: 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c  me the.** defaul
eb20: 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f  t behavior in so
eb30: 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
eb40: 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  e of SQLite..**.
eb50: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
eb60: 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65  s_init() routine
eb70: 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d   does operating-
eb80: 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a  system specific.
eb90: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ** initializatio
eba0: 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20  n of the SQLite 
ebb0: 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71  library.  The sq
ebc0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
ebd0: 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73  * routine undoes
ebe0: 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73   the effect of s
ebf0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
ec00: 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73  .  Typical tasks
ec10: 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79  .** performed by
ec20: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
ec30: 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69  include allocati
ec40: 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69  on or deallocati
ec50: 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20  on.** of static 
ec60: 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69  resources, initi
ec70: 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f  alization of glo
ec80: 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a  bal variables,.*
ec90: 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64  * setting up a d
eca0: 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
ecb0: 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20  vfs] module, or 
ecc0: 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20  setting up.** a 
ecd0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
ece0: 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c  ation using [sql
ecf0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a  ite3_config()]..
ed00: 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
ed10: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
ed20: 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  er invoke either
ed30: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
ed40: 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
ed50: 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74  _os_end() direct
ed60: 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  ly.  The applica
ed70: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79  tion should only
ed80: 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
ed90: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
eda0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74  and sqlite3_shut
edb0: 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c  down().  The sql
edc0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
edd0: 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63  * interface is c
ede0: 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61  alled automatica
edf0: 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69  lly by sqlite3_i
ee00: 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a  nitialize() and.
ee10: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ** sqlite3_os_en
ee20: 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79  d() is called by
ee30: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
ee40: 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74  n().  Appropriat
ee50: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
ee60: 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33  ions for sqlite3
ee70: 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
ee80: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
ee90: 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74  ** are built int
eea0: 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74  o SQLite when it
eeb0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72   is compiled for
eec0: 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20   Unix, Windows, 
eed0: 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e  or OS/2..** When
eee0: 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20   [custom builds 
eef0: 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65  | built for othe
ef00: 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20  r platforms].** 
ef10: 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49  (using the [SQLI
ef20: 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63  TE_OS_OTHER=1] c
ef30: 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
ef40: 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69  ption) the appli
ef50: 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70  cation must supp
ef60: 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d  ly a suitable im
ef70: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  plementation for
ef80: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  .** sqlite3_os_i
ef90: 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
efa0: 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20  3_os_end().  An 
efb0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70  application-supp
efc0: 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  lied.** implemen
efd0: 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
efe0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73  3_os_init() or s
eff0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
f000: 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b  ** must return [
f010: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
f020: 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f  ccess and some o
f030: 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65  ther [error code
f040: 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72  ] upon.** failur
f050: 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
f060: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69  3_initialize(voi
f070: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
f080: 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a  shutdown(void);.
f090: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  int sqlite3_os_i
f0a0: 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  nit(void);.int s
f0b0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f  qlite3_os_end(vo
f0c0: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
f0d0: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e  3REF: Configurin
f0e0: 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  g The SQLite Lib
f0f0: 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  rary.**.** The s
f100: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
f110: 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
f120: 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c  d to make global
f130: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
f140: 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c  * changes to SQL
f150: 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
f160: 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74  tune SQLite to t
f170: 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64  he specific need
f180: 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  s of.** the appl
f190: 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  ication.  The de
f1a0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
f1b0: 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ion is recommend
f1c0: 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61  ed for most.** a
f1d0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20  pplications and 
f1e0: 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  so this routine 
f1f0: 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e  is usually not n
f200: 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73  ecessary.  It is
f210: 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20  .** provided to 
f220: 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70  support rare app
f230: 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75  lications with u
f240: 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a  nusual needs..**
f250: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
f260: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
f270: 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64  ce is not thread
f280: 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69  safe.  The appli
f290: 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69  cation.** must i
f2a0: 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74  nsure that no ot
f2b0: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
f2c0: 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65  faces are invoke
f2d0: 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68  d by other.** th
f2e0: 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69  reads while sqli
f2f0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
f300: 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65  running.  Furthe
f310: 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63  rmore, sqlite3_c
f320: 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f  onfig().** may o
f330: 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70  nly be invoked p
f340: 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20  rior to library 
f350: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75  initialization u
f360: 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
f370: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f  _initialize()] o
f380: 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e  r after shutdown
f390: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75   by [sqlite3_shu
f3a0: 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66  tdown()]..** ^If
f3b0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
f3c0: 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65  ) is called afte
f3d0: 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  r [sqlite3_initi
f3e0: 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66  alize()] and bef
f3f0: 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
f400: 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e  shutdown()] then
f410: 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20   it will return 
f420: 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a  SQLITE_MISUSE..*
f430: 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c  * Note, however,
f440: 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63   that ^sqlite3_c
f450: 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63  onfig() can be c
f460: 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66  alled as part of
f470: 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
f480: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70  tation of an app
f490: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
f4a0: 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69   [sqlite3_os_ini
f4b0: 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  t()]..**.** The 
f4c0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
f4d0: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
f4e0: 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  () is an integer
f4f0: 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  .** [configurati
f500: 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
f510: 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
f520: 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
f530: 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
f540: 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
f550: 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
f560: 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
f570: 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69  ng on the [confi
f580: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
f590: 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
f5a0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
f5b0: 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75   ^When a configu
f5c0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
f5d0: 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f   set, sqlite3_co
f5e0: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b  nfig() returns [
f5f0: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e  SQLITE_OK]..** ^
f600: 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73  If the option is
f610: 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69   unknown or SQLi
f620: 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
f630: 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a  set the option.*
f640: 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * then this rout
f650: 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ine returns a no
f660: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
f670: 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  de]..*/.int sqli
f680: 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20  te3_config(int, 
f690: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
f6a0: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65  I3REF: Configure
f6b0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
f6c0: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tions.**.** The 
f6d0: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
f6e0: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
f6f0: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f   used to make co
f700: 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
f710: 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74  hanges to a [dat
f720: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
f730: 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63  ].  The interfac
f740: 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a  e is similar to.
f750: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
f760: 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61  ig()] except tha
f770: 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70  t the changes ap
f780: 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a  ply to a single.
f790: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
f7a0: 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66  nection] (specif
f7b0: 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
f7c0: 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a   argument)..**.*
f7d0: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
f7e0: 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
f7f0: 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e  _db_config(D,V,.
f800: 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b  ..)  is the.** [
f810: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
f820: 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66  LOOKASIDE | conf
f830: 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20  iguration verb] 
f840: 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  - an integer cod
f850: 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63  e .** that indic
f860: 61 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74  ates what aspect
f870: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
f880: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
f890: 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65   being configure
f8a0: 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74  d..** Subsequent
f8b0: 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20   arguments vary 
f8c0: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
f8d0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76   configuration v
f8e0: 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  erb..**.** ^Call
f8f0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f  s to sqlite3_db_
f900: 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20  config() return 
f910: 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64  SQLITE_OK if and
f920: 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20   only if.** the 
f930: 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72  call is consider
f940: 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a  ed successful..*
f950: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62  /.int sqlite3_db
f960: 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a  _config(sqlite3*
f970: 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a  , int op, ...);.
f980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
f990: 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
f9a0: 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a  on Routines.**.*
f9b0: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
f9c0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   this object def
f9d0: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
f9e0: 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74  ce between SQLit
f9f0: 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76  e.** and low-lev
fa00: 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
fa10: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  tion routines..*
fa20: 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  *.** This object
fa30: 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79   is used in only
fa40: 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68   one place in th
fa50: 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  e SQLite interfa
fa60: 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  ce..** A pointer
fa70: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
fa80: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  of this object i
fa90: 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
faa0: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
fab0: 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65  nfig()] when the
fac0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
fad0: 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c  ption is.** [SQL
fae0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
faf0: 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  C] or [SQLITE_CO
fb00: 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e  NFIG_GETMALLOC].
fb10: 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e    .** By creatin
fb20: 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  g an instance of
fb30: 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20   this object.** 
fb40: 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74  and passing it t
fb50: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
fb60: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
fb70: 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75  G_MALLOC]).** du
fb80: 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ring configurati
fb90: 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  on, an applicati
fba0: 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61  on can specify a
fbb0: 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
fbc0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
fbd0: 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72  on subsystem for
fbe0: 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66   SQLite to use f
fbf0: 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a  or all of its.**
fc00: 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
fc10: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  needs..**.** Not
fc20: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f  e that SQLite co
fc30: 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c  mes with several
fc40: 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72   [built-in memor
fc50: 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a  y allocators].**
fc60: 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63   that are perfec
fc70: 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72  tly adequate for
fc80: 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e   the overwhelmin
fc90: 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70  g majority of ap
fca0: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e  plications.** an
fcb0: 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65  d that this obje
fcc0: 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75  ct is only usefu
fcd0: 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f  l to a tiny mino
fce0: 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
fcf0: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65  ions.** with spe
fd00: 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20  cialized memory 
fd10: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69  allocation requi
fd20: 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f  rements.  This o
fd30: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f  bject is.** also
fd40: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
fd50: 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69  ting of SQLite i
fd60: 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69  n order to speci
fd70: 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
fd80: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
fd90: 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c  cator that simul
fda0: 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d  ates memory out-
fdb0: 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74  of-memory condit
fdc0: 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72  ions in.** order
fdd0: 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20   to verify that 
fde0: 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20  SQLite recovers 
fdf0: 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20  gracefully from 
fe00: 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f  such.** conditio
fe10: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  ns..**.** The xM
fe20: 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c  alloc, xRealloc,
fe30: 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f   and xFree metho
fe40: 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  ds must work lik
fe50: 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28  e the.** malloc(
fe60: 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  ), realloc() and
fe70: 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e   free() function
fe80: 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
fe90: 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
fea0: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
feb0: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65  tees that the se
fec0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
fed0: 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20  .** xRealloc is 
fee0: 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72  always a value r
fef0: 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69  eturned by a pri
ff00: 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e  or call to xRoun
ff10: 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65  dup..**.** xSize
ff20: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
ff30: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
ff40: 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  e of a memory al
ff50: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76  location.** prev
ff60: 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
ff70: 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20  from xMalloc or 
ff80: 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61  xRealloc.  The a
ff90: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a  llocated size.**
ffa0: 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65   is always at le
ffb0: 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68  ast as big as th
ffc0: 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  e requested size
ffd0: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
ffe0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  er..**.** The xR
fff0: 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65  oundup method re
10000 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64  turns what would
10010 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   be the allocate
10020 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d  d size of.** a m
10030 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10040 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75   given a particu
10050 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69  lar requested si
10060 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79  ze.  Most memory
10070 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  .** allocators r
10080 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61  ound up memory a
10090 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65  llocations at le
100a0 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ast to the next 
100b0 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38  multiple.** of 8
100c0 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f  .  Some allocato
100d0 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61  rs round up to a
100e0 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65   larger multiple
100f0 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f   or to a power o
10100 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65  f 2..** Every me
10110 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10120 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69  request coming i
10130 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74  n through [sqlit
10140 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  e3_malloc()].** 
10150 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
10160 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c  loc()] first cal
10170 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66  ls xRoundup.  If
10180 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e   xRoundup return
10190 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61  s 0, .** that ca
101a0 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70  uses the corresp
101b0 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c  onding memory al
101c0 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c  location to fail
101d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69  ..**.** The xIni
101e0 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c  t method initial
101f0 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  izes the memory 
10200 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72  allocator.  (For
10210 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20   example,.** it 
10220 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61  might allocate a
10230 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78  ny require mutex
10240 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65  es or initialize
10250 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a   internal data.*
10260 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54  * structures.  T
10270 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  he xShutdown met
10280 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  hod is invoked (
10290 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a  indirectly) by.*
102a0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
102b0 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c  own()] and shoul
102c0 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79  d deallocate any
102d0 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69   resources acqui
102e0 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e  red.** by xInit.
102f0 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70    The pAppData p
10300 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61  ointer is used a
10310 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
10320 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74  eter to.** xInit
10330 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a   and xShutdown..
10340 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c  **.** SQLite hol
10350 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
10360 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
10370 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69  ER] mutex when i
10380 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65  t invokes.** the
10390 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73   xInit method, s
103a0 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  o the xInit meth
103b0 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74  od need not be t
103c0 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a  hreadsafe.  The.
103d0 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  ** xShutdown met
103e0 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c  hod is only call
103f0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
10400 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20  _shutdown()] so 
10410 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e  it does.** not n
10420 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64  eed to be thread
10430 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f  safe either.  Fo
10440 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68  r all other meth
10450 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68  ods, SQLite.** h
10460 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
10470 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
10480 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67  M] mutex as long
10490 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   as the.** [SQLI
104a0 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
104b0 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  TUS] configurati
104c0 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72  on option is tur
104d0 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a  ned on (which.**
104e0 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c   it is by defaul
104f0 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65  t) and so the me
10500 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61  thods are automa
10510 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a  tically serializ
10520 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  ed..** However, 
10530 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  if [SQLITE_CONFI
10540 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20  G_MEMSTATUS] is 
10550 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74  disabled, then t
10560 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68  he other.** meth
10570 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65  ods must be thre
10580 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d  adsafe or else m
10590 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72  ake their own ar
105a0 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a  rangements for.*
105b0 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e  * serialization.
105c0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  .**.** SQLite wi
105d0 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ll never invoke 
105e0 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61  xInit() more tha
105f0 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61  n once without a
10600 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a  n intervening.**
10610 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f   call to xShutdo
10620 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  wn()..*/.typedef
10630 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
10640 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  mem_methods sqli
10650 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b  te3_mem_methods;
10660 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
10670 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  mem_methods {.  
10680 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29  void *(*xMalloc)
10690 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f  (int);         /
106a0 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * Memory allocat
106b0 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ion function */.
106c0 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28    void (*xFree)(
106d0 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
106e0 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72   /* Free a prior
106f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
10700 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f   void *(*xReallo
10710 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20  c)(void*,int);  
10720 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c  /* Resize an all
10730 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
10740 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29   (*xSize)(void*)
10750 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  ;           /* R
10760 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f  eturn the size o
10770 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  f an allocation 
10780 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e  */.  int (*xRoun
10790 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20  dup)(int);      
107a0 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20      /* Round up 
107b0 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20  request size to 
107c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
107d0 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74  */.  int (*xInit
107e0 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
107f0 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a      /* Initializ
10800 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
10810 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
10820 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f   (*xShutdown)(vo
10830 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65  id*);      /* De
10840 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  initialize the m
10850 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
10860 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
10870 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20  ata;            
10880 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20      /* Argument 
10890 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78  to xInit() and x
108a0 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b  Shutdown() */.};
108b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
108c0 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  : Configuration 
108d0 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  Options.** KEYWO
108e0 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74  RDS: {configurat
108f0 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a  ion option}.**.*
10900 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
10910 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
10920 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
10930 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10940 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
10950 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
10960 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
10970 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
10980 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
10990 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
109a0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
109b0 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
109c0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
109d0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
109e0 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
109f0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
10a00 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
10a10 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
10a20 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
10a30 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
10a40 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
10a50 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  e3_config()] to 
10a60 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
10a70 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
10a80 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  d.  The [sqlite3
10a90 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
10aa0 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
10ab0 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
10ac0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
10ad0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
10ae0 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
10af0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10b00 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
10b10 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
10b20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
10b30 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64  INGLETHREAD]] <d
10b40 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10b50 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74  SINGLETHREAD</dt
10b60 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
10b70 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
10b80 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
10b90 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
10ba0 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
10bb0 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69  ding mode] to Si
10bc0 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e  ngle-thread.  In
10bd0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74   other words, it
10be0 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c   disables.** all
10bf0 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75   mutexing and pu
10c00 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61  ts SQLite into a
10c10 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63   mode where it c
10c20 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a  an only be used.
10c30 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ** by a single t
10c40 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c  hread.   ^If SQL
10c50 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
10c60 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
10c70 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
10c80 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
10c90 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
10ca0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
10cb0 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
10cc0 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74  ible to change t
10cd0 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
10ce0 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66  de] from its def
10cf0 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  ault.** value of
10d00 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61   Single-thread a
10d10 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63  nd so [sqlite3_c
10d20 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
10d30 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  turn .** [SQLITE
10d40 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
10d50 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  d with the SQLIT
10d60 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
10d70 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75  HREAD.** configu
10d80 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
10d90 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
10da0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
10db0 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  HREAD]] <dt>SQLI
10dc0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
10dd0 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
10de0 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
10df0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
10e00 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
10e10 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
10e20 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
10e30 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72  de] to Multi-thr
10e40 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
10e50 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
10e60 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e  s.** mutexing on
10e70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
10e80 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
10e90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
10ea0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20  objects..** The 
10eb0 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72  application is r
10ec0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73  esponsible for s
10ed0 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73  erializing acces
10ee0 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73  s to.** [databas
10ef0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
10f00 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
10f10 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f  tements].  But o
10f20 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20  ther mutexes.** 
10f30 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74  are enabled so t
10f40 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
10f50 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69  be safe to use i
10f60 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
10f70 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e  ed.** environmen
10f80 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20  t as long as no 
10f90 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65  two threads atte
10fa0 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73  mpt to use the s
10fb0 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ame.** [database
10fc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20   connection] at 
10fd0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20  the same time.  
10fe0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
10ff0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
11000 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
11010 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
11020 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
11030 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
11040 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
11050 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
11060 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72  et the Multi-thr
11070 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
11080 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
11090 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
110a0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
110b0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
110c0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
110d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
110e0 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67  LTITHREAD config
110f0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
11100 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
11110 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
11120 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  LIZED]] <dt>SQLI
11130 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
11140 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  IZED</dt>.** <dd
11150 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
11160 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
11170 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
11180 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
11190 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
111a0 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64  e] to Serialized
111b0 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
111c0 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e  , this option en
111d0 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
111e0 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74  exes including t
111f0 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20  he recursive.** 
11200 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61  mutexes on [data
11210 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11220 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
11230 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
11240 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f  s..** In this mo
11250 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65  de (which is the
11260 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51   default when SQ
11270 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
11280 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45   with.** [SQLITE
11290 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20  _THREADSAFE=1]) 
112a0 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
112b0 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73  ry will itself s
112c0 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a  erialize access.
112d0 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20  ** to [database 
112e0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
112f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
11300 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74  ments] so that t
11310 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  he.** applicatio
11320 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65  n is free to use
11330 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
11340 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
11350 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b  or the.** same [
11360 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
11370 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74  nt] in different
11380 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
11390 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49  same time..** ^I
113a0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
113b0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
113c0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
113d0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
113e0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
113f0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
11400 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
11410 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
11420 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20   the Serialized 
11430 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
11440 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
11450 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
11460 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
11470 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
11480 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
11490 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
114a0 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69  IZED configurati
114b0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
114c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
114d0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c  ONFIG_MALLOC]] <
114e0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
114f0 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  _MALLOC</dt>.** 
11500 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
11510 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
11520 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
11530 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
11540 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
11550 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
11560 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
11570 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
11580 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
11590 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
115a0 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
115b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
115c0 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
115d0 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68  n place of.** th
115e0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
115f0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69  ion routines bui
11600 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
11610 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a  ^ ^SQLite makes.
11620 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ** its own priva
11630 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63  te copy of the c
11640 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
11650 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11660 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  ds] structure.**
11670 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c   before the [sql
11680 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63  ite3_config()] c
11690 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64  all returns.</dd
116a0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
116b0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
116c0 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  C]] <dt>SQLITE_C
116d0 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c  ONFIG_GETMALLOC<
116e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
116f0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
11700 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
11710 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
11720 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
11730 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
11740 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
11750 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
11760 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   The [sqlite3_me
11770 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  m_methods].** st
11780 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
11790 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
117a0 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d  ntly defined mem
117b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
117c0 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
117d0 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
117e0 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
117f0 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65  d the default me
11800 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
11810 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
11820 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20   a wrapper that 
11830 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f  simulations memo
11840 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
11850 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63  ilure or.** trac
11860 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c  ks memory usage,
11870 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f   for example. </
11880 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
11890 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
118a0 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TUS]] <dt>SQLITE
118b0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
118c0 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  S</dt>.** <dd> ^
118d0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
118e0 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  s single argumen
118f0 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69  t of type int, i
11900 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
11910 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69  .** boolean, whi
11920 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ch enables or di
11930 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65  sables the colle
11940 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20  ction of memory 
11950 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73  allocation .** s
11960 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65  tatistics. ^(Whe
11970 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
11980 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
11990 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  re disabled, the
119a0 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   .** following S
119b0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
119c0 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72   become non-oper
119d0 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75  ational:.**   <u
119e0 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  l>.**   <li> [sq
119f0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
11a00 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  d()].**   <li> [
11a10 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
11a20 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20  ighwater()].**  
11a30 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
11a40 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
11a50 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
11a60 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d  qlite3_status()]
11a70 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  .**   </ul>)^.**
11a80 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74   ^Memory allocat
11a90 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
11aa0 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
11ab0 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c  fault unless SQL
11ac0 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ite is.** compil
11ad0 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
11ae0 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
11af0 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61  S]=0 in which ca
11b00 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  se memory.** all
11b10 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
11b20 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  cs are disabled 
11b30 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c  by default..** <
11b40 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
11b50 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
11b60 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  CH]] <dt>SQLITE_
11b70 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f  CONFIG_SCRATCH</
11b80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
11b90 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
11ba0 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
11bb0 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
11bc0 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
11bd0 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  r.** scratch mem
11be0 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20  ory.  There are 
11bf0 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a  three arguments:
11c00 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38    A pointer an 8
11c10 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64  -byte.** aligned
11c20 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66   memory buffer f
11c30 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63  rom which the sc
11c40 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
11c50 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61  s will be.** dra
11c60 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  wn, the size of 
11c70 65 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c  each scratch all
11c80 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a  ocation (sz),.**
11c90 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d   and the maximum
11ca0 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74   number of scrat
11cb0 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28  ch allocations (
11cc0 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61  N).  The sz.** a
11cd0 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
11ce0 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36  a multiple of 16
11cf0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
11d00 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
11d10 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
11d20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62  8-byte aligned b
11d30 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c  uffer.** of at l
11d40 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
11d50 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
11d60 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e  QLite will use n
11d70 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20  o more than two 
11d80 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20  scratch buffers 
11d90 70 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a  per thread.  So.
11da0 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73  ** N should be s
11db0 65 74 20 74 6f 20 74 77 69 63 65 20 74 68 65 20  et to twice the 
11dc0 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d  expected maximum
11dd0 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61   number of threa
11de0 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ds..** ^SQLite w
11df0 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72  ill never requir
11e00 65 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66  e a scratch buff
11e10 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20  er that is more 
11e20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20  than 6.** times 
11e30 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
11e40 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69  e size. ^If SQLi
11e50 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61  te needs needs a
11e60 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72  dditional.** scr
11e70 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f  atch memory beyo
11e80 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
11e90 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66  ded by this conf
11ea0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11eb0 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69  , then .** [sqli
11ec0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69  te3_malloc()] wi
11ed0 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  ll be used to ob
11ee0 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  tain the memory 
11ef0 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  needed.</dd>.**.
11f00 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
11f10 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c  IG_PAGECACHE]] <
11f20 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
11f30 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a  _PAGECACHE</dt>.
11f40 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
11f50 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
11f60 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
11f70 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
11f80 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
11f90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
11fa0 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68  ge cache with th
11fb0 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63  e default page c
11fc0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
11fd0 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63  ion.  .** This c
11fe0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f  onfiguration sho
11ff0 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
12000 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  if an applicatio
12010 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a  n-define page.**
12020 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
12030 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20  ation is loaded 
12040 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  using the SQLITE
12050 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
12060 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65  option..** There
12070 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
12080 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
12090 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74  ion: A pointer t
120a0 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  o 8-byte aligned
120b0 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20  .** memory, the 
120c0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67  size of each pag
120d0 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61  e buffer (sz), a
120e0 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
120f0 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54   pages (N)..** T
12100 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73  he sz argument s
12110 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a  hould be the siz
12120 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  e of the largest
12130 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a   database page.*
12140 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77  * (a power of tw
12150 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e  o between 512 an
12160 64 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20  d 32768) plus a 
12170 6c 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72  little extra for
12180 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65   each.** page he
12190 61 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65  ader.  ^The page
121a0 20 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20   header size is 
121b0 32 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64  20 to 40 bytes d
121c0 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74  epending on.** t
121d0 68 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63  he host architec
121e0 74 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61  ture.  ^It is ha
121f0 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72  rmless, apart fr
12200 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65  om the wasted me
12210 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65  mory,.** to make
12220 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f   sz a little too
12230 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72   large.  The fir
12240 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  st.** argument s
12250 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61  hould point to a
12260 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20  n allocation of 
12270 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
12280 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
12290 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
122a0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
122b0 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69  ovided by the fi
122c0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
122d0 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d  satisfy its.** m
122e0 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20  emory needs for 
122f0 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65  the first N page
12300 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74  s that it adds t
12310 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64  o cache.  ^If ad
12320 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
12330 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
12340 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
12350 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
12360 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20  by this option, 
12370 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67  then.** SQLite g
12380 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
12390 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68  malloc()] for th
123a0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f  e additional sto
123b0 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54  rage space..** T
123c0 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68  he pointer in th
123d0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
123e0 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67   must.** be alig
123f0 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
12400 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
12410 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
12420 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69   of SQLite.** wi
12430 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
12440 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12450 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
12460 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12470 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a  NFIG_HEAP</dt>.*
12480 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
12490 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
124a0 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
124b0 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
124c0 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72   will use.** for
124d0 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
124e0 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  mic memory alloc
124f0 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f  ation needs beyo
12500 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65  nd those provide
12510 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c  d.** for by [SQL
12520 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
12530 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  CH] and [SQLITE_
12540 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
12550 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  ]..** There are 
12560 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a  three arguments:
12570 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   An 8-byte align
12580 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  ed pointer to th
12590 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65  e memory,.** the
125a0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
125b0 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62   in the memory b
125c0 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d  uffer, and the m
125d0 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
125e0 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74  n size..** ^If t
125f0 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
12600 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
12610 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74  nter) is NULL, t
12620 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72  hen SQLite rever
12630 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69  ts.** to using i
12640 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  ts default memor
12650 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65  y allocator (the
12660 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
12670 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29   implementation)
12680 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79  ,.** undoing any
12690 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f   prior invocatio
126a0 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  n of [SQLITE_CON
126b0 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49  FIG_MALLOC].  ^I
126c0 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  f the.** memory 
126d0 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
126e0 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b  ULL and either [
126f0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
12700 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51  MSYS3] or.** [SQ
12710 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
12720 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64  YS5] are defined
12730 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72  , then the alter
12740 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a  native memory.**
12750 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e   allocator is en
12760 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20  gaged to handle 
12770 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d  all of SQLites m
12780 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12790 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66   needs..** The f
127a0 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
127b0 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
127c0 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  ) must be aligne
127d0 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a  d to an 8-byte.*
127e0 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75  * boundary or su
127f0 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
12800 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  r of SQLite will
12810 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   be undefined..*
12820 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  * The minimum al
12830 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73  location size is
12840 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32   capped at 2**12
12850 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c  . Reasonable val
12860 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d  ues.** for the m
12870 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
12880 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20  n size are 2**5 
12890 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64  through 2**8.</d
128a0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
128b0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d  E_CONFIG_MUTEX]]
128c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
128d0 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  IG_MUTEX</dt>.**
128e0 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
128f0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
12900 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
12910 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
12920 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
12930 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
12940 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
12950 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
12960 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
12970 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
12980 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65  e low-level mute
12990 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  x routines to be
129a0 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a   used in place.*
129b0 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74  * the mutex rout
129c0 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
129d0 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69  SQLite.)^  ^SQLi
129e0 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
129f0 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e  of the.** conten
12a00 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
12a10 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
12a20 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72   structure befor
12a30 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  e the call to.**
12a40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12a50 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66  ()] returns. ^If
12a60 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
12a70 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
12a80 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
12a90 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
12aa0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
12ab0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
12ac0 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
12ad0 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
12ae0 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
12af0 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
12b00 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
12b10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
12b20 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
12b30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
12b40 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
12b50 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
12b60 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
12b70 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
12b80 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
12b90 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64  IG_GETMUTEX]] <d
12ba0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12bb0 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  GETMUTEX</dt>.**
12bc0 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
12bd0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
12be0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
12bf0 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
12c00 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
12c10 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
12c20 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
12c30 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
12c40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
12c50 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
12c60 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
12c70 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
12c80 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
12c90 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  ex routines.)^.*
12ca0 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
12cb0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
12cc0 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
12cd0 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69  t mutex allocati
12ce0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
12cf0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73  ith a wrapper us
12d00 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65  ed to track mute
12d10 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66  x usage for perf
12d20 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69  ormance.** profi
12d30 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c  ling or testing,
12d40 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20   for example.   
12d50 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
12d60 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
12d70 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
12d80 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
12d90 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
12da0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
12db0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
12dc0 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
12dd0 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
12de0 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
12df0 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
12e00 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
12e10 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
12e20 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
12e30 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67  _GETMUTEX config
12e40 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
12e50 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
12e60 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
12e70 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12e80 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
12e90 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  DE]] <dt>SQLITE_
12ea0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
12eb0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
12ec0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
12ed0 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20  s two arguments 
12ee0 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
12ef0 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65  he default.** me
12f00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12f10 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  for the lookasid
12f20 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
12f30 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64  or on each.** [d
12f40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12f50 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  on].  The first 
12f60 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
12f70 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
12f80 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
12f90 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65   slot and the se
12fa0 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62  cond is the numb
12fb0 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61  er of.** slots a
12fc0 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68  llocated to each
12fd0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
12fe0 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20  tion.)^  ^(This 
12ff0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
13000 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69  ** <i>default</i
13010 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65  > lookaside size
13020 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42  . The [SQLITE_DB
13030 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
13040 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71  ].** verb to [sq
13050 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
13060 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  )] can be used t
13070 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
13080 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67  kaside.** config
13090 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  uration on indiv
130a0 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e  idual connection
130b0 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s.)^ </dd>.**.**
130c0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
130d0 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  _PCACHE2]] <dt>S
130e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
130f0 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
13100 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
13110 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
13120 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
13130 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
13140 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
13150 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
13160 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65  ject.  This obje
13170 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  ct specifies the
13180 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f   interface.** to
13190 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63   a custom page c
131a0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
131b0 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ion.)^  ^SQLite 
131c0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
131d0 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e  the.** object an
131e0 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61  d uses it for pa
131f0 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
13200 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64  allocations.</dd
13210 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13220 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
13230 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
13240 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
13250 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
13260 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
13270 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13280 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
13290 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
132a0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
132b0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
132c0 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
132d0 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  s of the current
132e0 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69  .** page cache i
132f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
13300 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
13310 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
13320 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
13330 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  G]] <dt>SQLITE_C
13340 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a  ONFIG_LOG</dt>.*
13350 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
13360 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
13370 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
13380 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e  rguments: a poin
13390 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63  ter to a.** func
133a0 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c  tion with a call
133b0 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f   signature of vo
133c0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  id(*)(void*,int,
133d0 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a  const char*), .*
133e0 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20  * and a pointer 
133f0 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65  to void. ^If the
13400 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
13410 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69  r is not NULL, i
13420 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20  t is.** invoked 
13430 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  by [sqlite3_log(
13440 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61  )] to process ea
13450 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74  ch logging event
13460 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75  .  ^If the.** fu
13470 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
13480 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c  s NULL, the [sql
13490 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65  ite3_log()] inte
134a0 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20  rface becomes a 
134b0 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76  no-op..** ^The v
134c0 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74  oid pointer that
134d0 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   is the second a
134e0 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54  rgument to SQLIT
134f0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a  E_CONFIG_LOG is.
13500 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  ** passed throug
13510 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70  h as the first p
13520 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
13530 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
13540 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
13550 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20  nction whenever 
13560 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73  that function is
13570 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20   invoked.  ^The 
13580 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
13590 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65   to.** the logge
135a0 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20  r function is a 
135b0 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73  copy of the firs
135c0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
135d0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
135e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  .** [sqlite3_log
135f0 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20  ()] call and is 
13600 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61  intended to be a
13610 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
13620 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  r an.** [extende
13630 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20  d result code]. 
13640 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
13650 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20  meter passed to 
13660 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a  the logger is.**
13670 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74   log message aft
13680 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69  er formatting vi
13690 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  a [sqlite3_snpri
136a0 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53  ntf()]..** The S
136b0 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e  QLite logging in
136c0 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
136d0 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f  eentrant; the lo
136e0 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  gger function.**
136f0 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65   supplied by the
13700 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
13710 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79  t not invoke any
13720 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
13730 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69  e..** In a multi
13740 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63  -threaded applic
13750 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69  ation, the appli
13760 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
13770 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
13780 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  n must be thread
13790 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  safe. </dd>.**.*
137a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
137b0 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_URI]] <dt>SQLI
137c0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a  TE_CONFIG_URI.**
137d0 20 3c 64 64 3e 20 54 68 69 73 20 6f 70 74 69 6f   <dd> This optio
137e0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
137f0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
13800 65 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65  e int. If non-ze
13810 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20  ro, then.** URI 
13820 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
13830 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66  ally enabled. If
13840 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
13850 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49  s zero, then URI
13860 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20   handling.** is 
13870 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
13880 64 2e 20 49 66 20 55 52 49 20 68 61 6e 64 6c 69  d. If URI handli
13890 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65  ng is globally e
138a0 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65  nabled, all file
138b0 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20  names.** passed 
138c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
138d0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
138e0 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  en_v2()], [sqlit
138f0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a  e3_open16()] or.
13900 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ** specified as 
13910 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d  part of [ATTACH]
13920 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e   commands are in
13930 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
13940 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a  s, regardless.**
13950 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
13960 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ot the [SQLITE_O
13970 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
13980 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61   set when the da
13990 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
139a0 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
139b0 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c  If it is globall
139c0 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65  y disabled, file
139d0 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c  names are.** onl
139e0 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  y interpreted as
139f0 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c   URIs if the SQL
13a00 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61  ITE_OPEN_URI fla
13a10 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
13a20 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
13a30 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
13a40 65 64 2e 20 42 79 20 64 65 66 61 75 6c 74 2c 20  ed. By default, 
13a50 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
13a60 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61  globally.** disa
13a70 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c  bled. The defaul
13a80 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63  t value may be c
13a90 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c  hanged by compil
13aa0 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ing with the.** 
13ab0 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
13ac0 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
13ad0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13ae0 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
13af0 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74  INDEX_SCAN]] <dt
13b00 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  >SQLITE_CONFIG_C
13b10 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
13b20 41 4e 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20  AN.** <dd> This 
13b30 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
13b40 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 20 61 72  ingle integer ar
13b50 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
13b60 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 0a 2a  interpreted as.*
13b70 2a 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f  * a boolean in o
13b80 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f  rder to enable o
13b90 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73  r disable the us
13ba0 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e  e of covering in
13bb0 64 69 63 65 73 20 66 6f 72 0a 2a 2a 20 66 75 6c  dices for.** ful
13bc0 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e  l table scans in
13bd0 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d   the query optim
13be0 69 7a 65 72 2e 20 20 54 68 65 20 64 65 66 61 75  izer.  The defau
13bf0 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65  lt setting is de
13c00 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74  termined.** by t
13c10 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57  he [SQLITE_ALLOW
13c20 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
13c30 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SCAN] compile-ti
13c40 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73  me option, or is
13c50 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74   "on".** if that
13c60 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
13c70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e  tion is omitted.
13c80 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20  .** The ability 
13c90 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75  to disable the u
13ca0 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69  se of covering i
13cb0 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20  ndices for full 
13cc0 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69  table scans.** i
13cd0 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69  s because some i
13ce0 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64  ncorrectly coded
13cf0 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74   legacy applicat
13d00 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75  ions might malfu
13d10 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 61 6c 66 75 6e  nction.** malfun
13d20 63 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 6f  ction when the o
13d30 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65  ptimization is e
13d40 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69  nabled.  Providi
13d50 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74  ng the ability t
13d60 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65  o.** disable the
13d70 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c   optimization al
13d80 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20  lows the older, 
13d90 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f  buggy applicatio
13da0 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a  n code to work.*
13db0 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65  * without change
13dc0 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72   even with newer
13dd0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
13de0 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ite..**.** [[SQL
13df0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
13e00 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  E]] [[SQLITE_CON
13e10 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a  FIG_GETPCACHE]].
13e20 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
13e30 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20  NFIG_PCACHE and 
13e40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13e50 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20  TPCACHE.** <dd> 
13e60 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72  These options ar
13e70 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73  e obsolete and s
13e80 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
13e90 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a  d by new code..*
13ea0 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69  * They are retai
13eb0 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ned for backward
13ec0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
13ed0 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f  but are now no-o
13ee0 70 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  ps..** </dl>.**.
13ef0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13f00 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c  IG_SQLLOG]].** <
13f10 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13f20 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54  _SQLLOG.** <dd>T
13f30 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  his option is on
13f40 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
13f50 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  sqlite is compil
13f60 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
13f70 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c  QLITE_ENABLE_SQL
13f80 4c 4f 47 20 70 72 65 2d 70 72 6f 63 65 73 73 6f  LOG pre-processo
13f90 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e  r macro defined.
13fa0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
13fb0 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65  ent should.** be
13fc0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
13fd0 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65  function of type
13fe0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
13ff0 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68  qlite3*,const ch
14000 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68  ar*, int)..** Th
14010 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20  e second should 
14020 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  be of type (void
14030 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  *). The callback
14040 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74   is invoked by t
14050 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e  he library.** in
14060 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20   three separate 
14070 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69  circumstances, i
14080 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
14090 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
140a0 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
140b0 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65  arameter. If the
140c0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
140d0 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65  r is 0, then the
140e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
140f0 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61  tion.** passed a
14100 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
14110 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62  ument has just b
14120 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20  een opened. The 
14130 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a  third argument.*
14140 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75  * points to a bu
14150 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ffer containing 
14160 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
14170 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69  main database fi
14180 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f  le. If the.** fo
14190 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
141a0 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51  s 1, then the SQ
141b0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
141c0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
141d0 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74  eter.** points t
141e0 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20  o has just been 
141f0 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66  executed. Or, if
14200 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
14210 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e  meter is 2, then
14220 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  .** the connecti
14230 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20  on being passed 
14240 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
14250 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67  rameter is being
14260 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20   closed. The.** 
14270 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
14280 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49  is passed NULL I
14290 6e 20 74 68 69 73 20 63 61 73 65 2e 0a 2a 2a 0a  n this case..**.
142a0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
142b0 49 47 5f 4d 4d 41 50 5f 4c 49 4d 49 54 5d 5d 0a  IG_MMAP_LIMIT]].
142c0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
142d0 4e 46 49 47 5f 4d 4d 41 50 5f 4c 49 4d 49 54 0a  NFIG_MMAP_LIMIT.
142e0 2a 2a 20 3c 64 64 3e 54 68 65 20 73 6f 6c 65 20  ** <dd>The sole 
142f0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
14300 62 65 20 61 20 36 34 2d 62 69 74 20 69 6e 74 65  be a 64-bit inte
14310 67 65 72 20 28 61 6e 20 73 71 6c 69 74 65 33 5f  ger (an sqlite3_
14320 69 6e 74 36 34 29 20 74 68 61 74 0a 2a 2a 20 69  int64) that.** i
14330 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 61  s the default ma
14340 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
14350 62 79 74 65 73 20 6f 66 20 70 72 6f 63 65 73 73  bytes of process
14360 20 61 64 64 72 65 73 73 20 73 70 61 63 65 20 74   address space t
14370 68 61 74 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  hat.** should be
14380 20 75 73 65 64 20 66 6f 72 20 61 63 63 65 73 73   used for access
14390 69 6e 67 20 65 61 63 68 20 64 61 74 61 62 61 73  ing each databas
143a0 65 20 66 69 6c 65 20 75 73 69 6e 67 20 6d 65 6d  e file using mem
143b0 6f 72 79 20 6d 61 70 70 69 6e 67 2e 0a 2a 2a 20  ory mapping..** 
143c0 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
143d0 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72  ing can be overr
143e0 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61  idden by each da
143f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14400 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65  n using.** eithe
14410 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d  r the [PRAGMA mm
14420 61 70 5f 6c 69 6d 69 74 5d 20 63 6f 6d 6d 61 6e  ap_limit] comman
14430 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74  d, or by using t
14440 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
14450 4e 54 4c 5f 4d 4d 41 50 5f 4c 49 4d 49 54 5d 20  NTL_MMAP_LIMIT] 
14460 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 54  file control.  T
14470 68 65 20 76 61 6c 75 65 20 73 65 74 20 68 65 72  he value set her
14480 65 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  e overrides the.
14490 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
144a0 64 65 66 61 75 6c 74 20 74 68 61 74 20 69 73 20  default that is 
144b0 73 65 74 20 75 73 69 6e 67 20 5b 53 51 4c 49 54  set using [SQLIT
144c0 45 5f 44 45 46 41 55 4c 54 5f 4d 4d 41 50 5f 4c  E_DEFAULT_MMAP_L
144d0 49 4d 49 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  IMIT]..** If the
144e0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69   argument to thi
144f0 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61  s option is nega
14500 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  tive, then.** th
14510 65 20 6d 65 6d 6f 72 79 20 6d 61 70 20 6c 69 6d  e memory map lim
14520 69 74 20 69 73 20 73 65 74 20 74 6f 20 74 68 65  it is set to the
14530 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65   compile-time de
14540 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  fault..** </dl>.
14550 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14560 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
14570 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
14580 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14590 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
145a0 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
145b0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
145c0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
145d0 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
145e0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
145f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
14600 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
14610 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
14620 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
14630 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14640 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
14650 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
14660 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
14670 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14680 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
14690 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
146a0 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
146b0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
146c0 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20  G_PAGECACHE     
146d0 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  7  /* void*, int
146e0 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
146f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14700 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20  FIG_HEAP        
14710 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    8  /* void*, i
14720 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69  nt nByte, int mi
14730 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
14740 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
14750 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62  ATUS     9  /* b
14760 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
14770 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14780 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20  MUTEX        10 
14790 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
147a0 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
147b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
147c0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20  FIG_GETMUTEX    
147d0 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   11  /* sqlite3_
147e0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
147f0 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  /./* previously 
14800 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48  SQLITE_CONFIG_CH
14810 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63  UNKALLOC 12 whic
14820 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e  h is now unused.
14830 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c   */ .#define SQL
14840 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
14850 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69  SIDE    13  /* i
14860 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
14870 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14880 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20  PCACHE       14 
14890 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
148a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
148b0 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20  IG_GETPCACHE    
148c0 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  15  /* no-op */.
148d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
148e0 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20  ONFIG_LOG       
148f0 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c     16  /* xFunc,
14900 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
14910 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14920 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20  URI          17 
14930 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
14940 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
14950 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38  _PCACHE2      18
14960 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
14970 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
14980 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14990 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
149a0 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74  2   19  /* sqlit
149b0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
149c0 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
149d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
149e0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
149f0 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23   20  /* int */.#
14a00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14a10 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20  NFIG_SQLLOG     
14a20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67    21  /* xSqllog
14a30 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69  , void* */.#defi
14a40 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
14a50 5f 4d 4d 41 50 5f 4c 49 4d 49 54 20 20 20 32 32  _MMAP_LIMIT   22
14a60 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74    /* sqlite3_int
14a70 36 34 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  64 */../*.** CAP
14a80 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
14a90 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69  Connection Confi
14aa0 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
14ab0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
14ac0 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
14ad0 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
14ae0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14af0 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
14b00 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
14b10 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
14b20 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
14b30 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
14b40 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
14b50 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
14b60 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
14b70 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
14b80 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
14b90 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
14ba0 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
14bb0 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
14bc0 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
14bd0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
14be0 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
14bf0 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
14c00 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  om [sqlite3_db_c
14c10 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
14c20 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
14c30 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
14c40 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62  ^The [sqlite3_db
14c50 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
14c60 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
14c70 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
14c80 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
14c90 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
14ca0 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
14cb0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
14cc0 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
14cd0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
14ce0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
14cf0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
14d00 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
14d10 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72  option takes thr
14d20 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  ee additional ar
14d30 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
14d40 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b  ermine the .** [
14d50 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
14d60 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66   allocator] conf
14d70 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68  iguration for th
14d80 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
14d90 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65  ection]..** ^The
14da0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
14db0 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  (the third param
14dc0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
14dd0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73  _db_config()] is
14de0 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
14df0 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72   a memory buffer
14e00 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b   to use for look
14e10 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  aside memory..**
14e20 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
14e30 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53  ment after the S
14e40 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
14e50 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a  OOKASIDE verb.**
14e60 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20   may be NULL in 
14e70 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74  which case SQLit
14e80 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20  e will allocate 
14e90 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65  the.** lookaside
14ea0 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75   buffer itself u
14eb0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61  sing [sqlite3_ma
14ec0 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65  lloc()]. ^The se
14ed0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
14ee0 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
14ef0 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
14f00 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68  uffer slot.  ^Th
14f10 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
14f20 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
14f30 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65  f.** slots.  The
14f40 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
14f50 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  fer in the first
14f60 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
14f70 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a  e greater than.*
14f80 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68  * or equal to th
14f90 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65  e product of the
14fa0 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72   second and thir
14fb0 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68  d arguments.  Th
14fc0 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74  e buffer.** must
14fd0 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
14fe0 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
14ff0 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f  y.  ^If the seco
15000 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
15010 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  * SQLITE_DBCONFI
15020 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e  G_LOOKASIDE is n
15030 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ot a multiple of
15040 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e   8, it is intern
15050 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20  ally.** rounded 
15060 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74  down to the next
15070 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c   smaller multipl
15080 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c  e of 8.  ^(The l
15090 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a  ookaside memory.
150a0 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
150b0 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20   for a database 
150c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f  connection can o
150d0 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77  nly be changed w
150e0 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e  hen that.** conn
150f0 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75  ection is not cu
15100 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f  rrently using lo
15110 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20  okaside memory, 
15120 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  or in other word
15130 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63  s.** when the "c
15140 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65  urrent value" re
15150 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
15160 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d  lite3_db_status]
15170 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  (D,[SQLITE_CONFI
15180 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e  G_LOOKASIDE],...
15190 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e  ) is zero..** An
151a0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61  y attempt to cha
151b0 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
151c0 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75  e memory configu
151d0 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b  ration when look
151e0 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  aside.** memory 
151f0 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73  is in use leaves
15200 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
15210 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64  on unchanged and
15220 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51   returns .** [SQ
15230 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64  LITE_BUSY].)^</d
15240 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
15250 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
15260 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a  BLE_FKEY</dt>.**
15270 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
15280 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
15290 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
152a0 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20  the enforcement 
152b0 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  of.** [foreign k
152c0 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e  ey constraints].
152d0 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62    There should b
152e0 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
152f0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
15300 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15310 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
15320 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
15330 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  sable FK enforce
15340 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  ment,.** positiv
15350 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65  e to enable FK e
15360 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65  nforcement or ne
15370 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
15380 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a  FK enforcement.*
15390 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  * unchanged.  Th
153a0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
153b0 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
153c0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
153d0 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
153e0 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
153f0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
15400 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  r FK enforcement
15410 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a   is off or on.**
15420 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
15430 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
15440 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
15450 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
15460 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
15470 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72  ase the FK enfor
15480 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69  cement setting i
15490 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
154a0 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
154b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
154c0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
154d0 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GER</dt>.** <dd>
154e0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
154f0 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
15500 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41  or disable [CREA
15510 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
15520 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65  ggers]..** There
15530 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
15540 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
15550 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
15560 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
15570 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
15580 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74  s 0 to disable t
15590 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69  riggers,.** posi
155a0 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74  tive to enable t
155b0 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74  riggers or negat
155c0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65  ive to leave the
155d0 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67   setting unchang
155e0 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
155f0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
15600 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
15610 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
15620 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
15630 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
15640 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67  te whether trigg
15650 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ers are disabled
15660 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
15670 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
15680 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
15690 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
156a0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
156b0 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
156c0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65  e the trigger se
156d0 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
156e0 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
156f0 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  >.**.** </dl>.*/
15700 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15710 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
15720 44 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f  DE       1001  /
15730 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20  * void* int int 
15740 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15750 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
15760 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20  E_FKEY     1002 
15770 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
15780 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
15790 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
157a0 52 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a  RIGGER  1003  /*
157b0 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f   int int* */.../
157c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
157d0 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
157e0 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
157f0 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68   Codes.**.** ^Th
15800 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
15810 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
15820 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  ) routine enable
15830 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
15840 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  e.** [extended r
15850 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
15860 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20  ture of SQLite. 
15870 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65  ^The extended re
15880 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72  sult.** codes ar
15890 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
158a0 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
158b0 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
158c0 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ty..*/.int sqlit
158d0 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
158e0 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33  lt_codes(sqlite3
158f0 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  *, int onoff);..
15900 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
15910 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
15920 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e  d.**.** ^Each en
15930 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65  try in an SQLite
15940 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69   table has a uni
15950 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  que 64-bit signe
15960 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79  d.** integer key
15970 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57   called the [ROW
15980 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e  ID | "rowid"]. ^
15990 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77  The rowid is alw
159a0 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a  ays available.**
159b0 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65   as an undeclare
159c0 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52  d column named R
159d0 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52  OWID, OID, or _R
159e0 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73  OWID_ as long as
159f0 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20   those.** names 
15a00 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65  are not also use
15a10 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20  d by explicitly 
15a20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73  declared columns
15a30 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62  . ^If.** the tab
15a40 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20  le has a column 
15a50 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52  of type [INTEGER
15a60 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68   PRIMARY KEY] th
15a70 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a  en that column.*
15a80 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69  * is another ali
15a90 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64  as for the rowid
15aa0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  ..**.** ^This ro
15ab0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
15ac0 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
15ad0 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20   most recent.** 
15ae0 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
15af0 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74  RT] into the dat
15b00 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b  abase from the [
15b10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15b20 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
15b30 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20  irst argument.  
15b40 5e 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65  ^As of SQLite ve
15b50 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 74 68 69  rsion 3.7.7, thi
15b60 73 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65  s routines.** re
15b70 63 6f 72 64 73 20 74 68 65 20 6c 61 73 74 20 69  cords the last i
15b80 6e 73 65 72 74 20 72 6f 77 69 64 20 6f 66 20 62  nsert rowid of b
15b90 6f 74 68 20 6f 72 64 69 6e 61 72 79 20 74 61 62  oth ordinary tab
15ba0 6c 65 73 20 61 6e 64 20 5b 76 69 72 74 75 61 6c  les and [virtual
15bb0 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 66   tables]..** ^If
15bc0 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b   no successful [
15bd0 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65  INSERT]s.** have
15be0 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f   ever occurred o
15bf0 6e 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20  n that database 
15c00 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f  connection, zero
15c10 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
15c20 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53  .** ^(If an [INS
15c30 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68  ERT] occurs with
15c40 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 20  in a trigger or 
15c50 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61  within a [virtua
15c60 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68  l table].** meth
15c70 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f  od, then this ro
15c80 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72  utine will retur
15c90 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  n the [rowid] of
15ca0 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a   the inserted.**
15cb0 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20   row as long as 
15cc0 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
15cd0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74  irtual table met
15ce0 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  hod is running..
15cf0 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20  ** But once the 
15d00 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
15d10 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  al table method 
15d20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20  ends, the value 
15d30 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20  returned .** by 
15d40 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76  this routine rev
15d50 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20  erts to what it 
15d60 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74  was before the t
15d70 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
15d80 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f  l.** table metho
15d90 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a  d began.)^.**.**
15da0 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68   ^An [INSERT] th
15db0 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20  at fails due to 
15dc0 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
15dd0 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a  lation is not a.
15de0 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
15df0 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20  NSERT] and does 
15e00 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
15e10 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
15e20 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
15e30 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20  .  ^Thus INSERT 
15e40 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20  OR FAIL, INSERT 
15e50 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52  OR IGNORE, INSER
15e60 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a  T OR ROLLBACK,.*
15e70 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20  * and INSERT OR 
15e80 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68  ABORT make no ch
15e90 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74  anges to the ret
15ea0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
15eb0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65  s.** routine whe
15ec0 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f  n their insertio
15ed0 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e  n fails.  ^(When
15ee0 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
15ef0 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73  CE.** encounters
15f00 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
15f10 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73  olation, it does
15f20 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a   not fail.  The.
15f30 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e  ** INSERT contin
15f40 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  ues to completio
15f50 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67  n after deleting
15f60 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65   rows that cause
15f70 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61  d.** the constra
15f80 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49  int problem so I
15f90 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
15fa0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61   will always cha
15fb0 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72  nge.** the retur
15fc0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
15fd0 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a  interface.)^.**.
15fe0 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
15ff0 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75  oses of this rou
16000 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54  tine, an [INSERT
16010 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  ] is considered 
16020 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73  to.** be success
16030 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69  ful even if it i
16040 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72  s subsequently r
16050 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
16060 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
16070 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f  is accessible to
16080 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
16090 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74  via the.** [last
160a0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20  _insert_rowid() 
160b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
160c0 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
160d0 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72  te thread perfor
160e0 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54  ms a new [INSERT
160f0 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  ] on the same.**
16100 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16110 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b  tion while the [
16120 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
16130 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20  ert_rowid()].** 
16140 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
16150 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61  ing and thus cha
16160 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e  nges the last in
16170 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a  sert [rowid],.**
16180 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
16190 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
161a0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
161b0 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20  _rowid()] is.** 
161c0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
161d0 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61  d might not equa
161e0 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64  l either the old
161f0 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c   or the new.** l
16200 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
16210 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  d]..*/.sqlite3_i
16220 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
16230 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
16240 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
16250 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
16260 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
16270 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
16280 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
16290 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
162a0 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65  mber of database
162b0 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20   rows that were 
162c0 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e  changed.** or in
162d0 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
162e0 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
162f0 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
16300 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
16310 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  * on the [databa
16320 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
16330 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
16340 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
16350 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67  .** ^(Only chang
16360 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65  es that are dire
16370 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62  ctly specified b
16380 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20  y the [INSERT], 
16390 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20  [UPDATE],.** or 
163a0 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
163b0 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20  nt are counted. 
163c0 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   Auxiliary chang
163d0 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20  es caused by.** 
163e0 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72  triggers or [for
163f0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
16400 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  ] are not counte
16410 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20  d.)^ Use the.** 
16420 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
16430 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69  hanges()] functi
16440 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  on to find the t
16450 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63  otal number of c
16460 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64  hanges.** includ
16470 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73  ing changes caus
16480 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61  ed by triggers a
16490 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  nd foreign key a
164a0 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ctions..**.** ^C
164b0 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
164c0 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61   that are simula
164d0 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45  ted by an [INSTE
164e0 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a  AD OF trigger].*
164f0 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  * are not counte
16500 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61  d.  Only real ta
16510 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20  ble changes are 
16520 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  counted..**.** ^
16530 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20  (A "row change" 
16540 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61  is a change to a
16550 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61   single row of a
16560 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a   single table.**
16570 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e   caused by an IN
16580 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72  SERT, DELETE, or
16590 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
165a0 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a  t.  Rows that.**
165b0 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20   are changed as 
165c0 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20  side effects of 
165d0 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
165e0 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  aint resolution,
165f0 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42  .** rollback, AB
16600 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
16610 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72  [DROP TABLE], or
16620 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a   by any other.**
16630 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e   mechanisms do n
16640 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65  ot count as dire
16650 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29  ct row changes.)
16660 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67  ^.**.** A "trigg
16670 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61  er context" is a
16680 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74   scope of execut
16690 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20  ion that begins 
166a0 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68  and.** ends with
166b0 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61   the script of a
166c0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
166d0 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a   | trigger]. .**
166e0 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d   Most SQL statem
166f0 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c  ents are.** eval
16700 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66  uated outside of
16710 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54   any trigger.  T
16720 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20  his is the "top 
16730 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65  level".** trigge
16740 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61  r context.  If a
16750 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66   trigger fires f
16760 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
16770 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67  l, a.** new trig
16780 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65  ger context is e
16790 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64  ntered for the d
167a0 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20  uration of that 
167b0 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20  one.** trigger. 
167c0 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65   Subtriggers cre
167d0 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20  ate subcontexts 
167e0 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69  for their durati
167f0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  on..**.** ^Calli
16800 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ng [sqlite3_exec
16810 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
16820 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76  step()] recursiv
16830 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ely does.** not 
16840 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69  create a new tri
16850 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
16860 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
16870 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
16880 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20  umber of direct 
16890 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74  row changes in t
168a0 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  he.** most recen
168b0 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
168c0 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  , or DELETE stat
168d0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
168e0 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72   same.** trigger
168f0 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
16900 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c  ^Thus, when call
16910 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  ed from the top 
16920 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63  level, this func
16930 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
16940 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  .** number of ch
16950 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
16960 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
16970 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
16980 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20  TE.** that also 
16990 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20  occurred at the 
169a0 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69  top level.  ^(Wi
169b0 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
169c0 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74   a trigger,.** t
169d0 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
169e0 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  es() interface c
169f0 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20  an be called to 
16a00 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
16a10 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e  of.** changes in
16a20 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
16a30 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
16a40 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
16a50 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
16a60 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62  ent within the b
16a70 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ody of the same 
16a80 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65  trigger..** Howe
16a90 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ver, the number 
16aa0 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
16ab0 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
16ac0 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73  s.** caused by s
16ad0 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65  ubtriggers since
16ae0 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69   those have thei
16af0 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e  r own context.)^
16b00 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
16b10 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
16b20 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
16b30 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
16b40 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
16b50 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
16b60 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
16b70 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
16b80 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
16b90 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
16ba0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
16bb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16bc0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
16bd0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
16be0 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
16bf0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
16c00 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
16c10 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
16c20 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
16c30 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
16c40 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
16c50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
16c60 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
16c70 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a  ws Modified.**.*
16c80 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
16c90 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
16ca0 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67  ber of row chang
16cb0 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e  es caused by [IN
16cc0 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54  SERT],.** [UPDAT
16cd0 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  E] or [DELETE] s
16ce0 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20  tatements since 
16cf0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
16d00 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70  nnection] was op
16d10 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63  ened..** ^(The c
16d20 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79  ount returned by
16d30 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
16d40 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65  hanges() include
16d50 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a  s all changes.**
16d60 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54   from all [CREAT
16d70 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
16d80 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e  ger] contexts an
16d90 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62  d changes made b
16da0 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  y.** [foreign ke
16db0 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65  y actions]. Howe
16dc0 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e  ver,.** the coun
16dd0 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
16de0 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20  de changes used 
16df0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45  to implement [RE
16e00 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e  PLACE] constrain
16e10 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61  ts,.** do rollba
16e20 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f  cks or ABORT pro
16e30 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f  cessing, or [DRO
16e40 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73  P TABLE] process
16e50 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75  ing.  The.** cou
16e60 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
16e70 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77  ude rows of view
16e80 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b  s that fire an [
16e90 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
16ea0 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69  er],.** though i
16eb0 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46  f the INSTEAD OF
16ec0 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63   trigger makes c
16ed0 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77  hanges of its ow
16ee0 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73  n, those changes
16ef0 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64   .** are counted
16f00 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .)^.** ^The sqli
16f10 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
16f20 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75  s() function cou
16f30 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20  nts the changes 
16f40 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68  as soon as.** th
16f50 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  e statement that
16f60 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63   makes them is c
16f70 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74  ompleted (when t
16f80 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e  he statement han
16f90 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64  dle.** is passed
16fa0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
16fb0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
16fc0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a  3_finalize()])..
16fd0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
16fe0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
16ff0 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
17000 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
17010 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
17020 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f   and the [total_
17030 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
17040 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
17050 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
17060 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
17070 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
17080 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17090 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
170a0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
170b0 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
170c0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
170d0 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
170e0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
170f0 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
17100 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
17110 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
17120 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
17130 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
17140 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
17150 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  g Query.**.** ^T
17160 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
17170 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
17180 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
17190 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
171a0 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
171b0 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
171c0 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
171d0 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
171e0 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
171f0 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
17200 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
17210 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
17220 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
17230 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
17240 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
17250 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
17260 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
17270 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  y..**.** ^It is 
17280 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
17290 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
172a0 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
172b0 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
172c0 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
172d0 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
172e0 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
172f0 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
17300 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
17310 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
17320 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
17330 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
17340 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
17350 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
17360 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
17370 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
17380 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  rns..**.** ^If a
17390 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
173a0 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
173b0 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
173c0 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
173d0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
173e0 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
173f0 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
17400 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
17410 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
17420 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
17430 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
17440 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41  letion..**.** ^A
17450 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
17460 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
17470 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
17480 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
17490 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69  T]..** ^If the i
174a0 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
174b0 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
174c0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
174d0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
174e0 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
174f0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
17500 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
17510 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
17520 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
17530 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
17540 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ally..**.** ^The
17550 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
17560 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
17570 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
17580 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
17590 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
175a0 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
175b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
175c0 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79   complete.  ^Any
175d0 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   new SQL stateme
175e0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
175f0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
17600 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
17610 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62  upt() call and b
17620 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75  efore the .** ru
17630 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  nning statements
17640 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
17650 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73  e interrupted as
17660 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65   if they had bee
17670 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69  n.** running pri
17680 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  or to the sqlite
17690 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
176a0 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74  ll.  ^New SQL st
176b0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
176c0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
176d0 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73  er the running s
176e0 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72  tatement count r
176f0 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a  eaches zero are.
17700 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20  ** not effected 
17710 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
17720 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e  nterrupt()..** ^
17730 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
17740 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
17750 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
17760 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
17770 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
17780 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
17790 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
177a0 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
177b0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
177c0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
177d0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
177e0 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
177f0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  urns..**.** If t
17800 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
17810 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
17820 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
17830 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20  errupt()].** is 
17840 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
17850 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
17860 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76  ely happen..*/.v
17870 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
17880 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
17890 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
178a0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
178b0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
178c0 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
178d0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
178e0 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
178f0 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
17900 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
17910 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
17920 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
17930 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
17940 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
17950 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
17960 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
17970 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
17980 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
17990 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
179a0 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
179b0 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
179c0 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
179d0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
179e0 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
179f0 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
17a00 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
17a10 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
17a20 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
17a30 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
17a40 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
17a50 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
17a60 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
17a70 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
17a80 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
17a90 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
17aa0 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
17ab0 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
17ac0 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
17ad0 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
17ae0 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
17af0 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
17b00 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
17b10 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
17b20 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
17b30 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
17b40 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
17b50 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
17b60 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
17b70 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
17b80 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
17b90 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
17ba0 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
17bb0 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
17bc0 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
17bd0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
17be0 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
17bf0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
17c00 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
17c10 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
17c20 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
17c30 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
17c40 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
17c50 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
17c60 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
17c70 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
17c80 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
17c90 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
17ca0 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
17cb0 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
17cc0 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
17cd0 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
17ce0 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
17cf0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
17d00 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
17d10 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
17d20 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
17d30 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
17d40 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
17d50 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
17d60 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
17d70 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
17d80 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
17d90 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
17da0 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
17db0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
17dc0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
17dd0 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
17de0 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
17df0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
17e00 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
17e10 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
17e20 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
17e30 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
17e40 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
17e50 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
17e60 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
17e70 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
17e80 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
17e90 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
17ea0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
17eb0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
17ec0 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
17ed0 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74  te order..*/.int
17ee0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
17ef0 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
17f00 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
17f10 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
17f20 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
17f30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
17f40 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
17f50 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
17f60 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
17f70 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
17f80 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61  ne sets a callba
17f90 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ck function that
17fa0 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
17fb0 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  d whenever.** an
17fc0 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
17fd0 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62   to open a datab
17fe0 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61  ase table that a
17ff0 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
18000 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
18010 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  locked..**.** ^I
18020 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
18030 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ack is NULL, the
18040 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
18050 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
18060 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20  _BLOCKED].** is 
18070 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
18080 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e  tely upon encoun
18090 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e  tering the lock.
180a0 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63    ^If the busy c
180b0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f  allback.** is no
180c0 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  t NULL, then the
180d0 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   callback might 
180e0 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
180f0 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  two arguments..*
18100 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
18110 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
18120 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
18130 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
18140 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  id* pointer whic
18150 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72  h.** is the thir
18160 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
18170 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
18180 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f  er().  ^The seco
18190 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
181a0 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
181b0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
181c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  he number of tim
181d0 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79  es that the busy
181e0 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20   handler has.** 
181f0 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72  been invoked for
18200 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76   this locking ev
18210 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
18220 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72   busy callback r
18230 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e  eturns 0, then n
18240 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74  o additional att
18250 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74  empts are made t
18260 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20  o.** access the 
18270 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51  database and [SQ
18280 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
18290 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
182a0 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64  KED] is returned
182b0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
182c0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
182d0 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
182e0 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
182f0 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
18300 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72  the database for
18310 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65   reading and the
18320 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
18330 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
18340 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
18350 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
18360 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20  arantee that it 
18370 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  will be invoked.
18380 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ** when there is
18390 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
183a0 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74  . ^If SQLite det
183b0 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
183c0 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
183d0 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
183e0 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
183f0 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
18400 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
18410 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
18420 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  ** or [SQLITE_IO
18430 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73  ERR_BLOCKED] ins
18440 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
18450 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
18460 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
18470 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
18480 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
18490 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
184a0 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
184b0 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
184c0 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
184d0 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
184e0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
184f0 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
18500 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
18510 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
18520 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
18530 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
18540 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
18550 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
18560 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
18570 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
18580 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
18590 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
185a0 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
185b0 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
185c0 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
185d0 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
185e0 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
185f0 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
18600 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
18610 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
18620 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
18630 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
18640 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
18650 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
18660 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
18670 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
18680 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
18690 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
186a0 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
186b0 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
186c0 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
186d0 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
186e0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
186f0 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
18700 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  is NULL..**.** ^
18710 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  The [SQLITE_BUSY
18720 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65  ] error is conve
18730 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f  rted to [SQLITE_
18740 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
18750 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  * when SQLite is
18760 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f   in the middle o
18770 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61  f a large transa
18780 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20  ction where all 
18790 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77  the.** changes w
187a0 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f  ill not fit into
187b0 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63   the in-memory c
187c0 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69  ache.  SQLite wi
187d0 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f  ll.** already ho
187e0 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f  ld a RESERVED lo
187f0 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  ck on the databa
18800 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20  se file, but it 
18810 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d  needs.** to prom
18820 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f  ote this lock to
18830 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68   EXCLUSIVE so th
18840 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20  at it can spill 
18850 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69  cache.** pages i
18860 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
18870 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61   file without ha
18880 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74  rm to concurrent
18890 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49  .** readers.  ^I
188a0 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  f it is unable t
188b0 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f  o promote the lo
188c0 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d  ck, then the in-
188d0 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20  memory.** cache 
188e0 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20  will be left in 
188f0 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20  an inconsistent 
18900 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65  state and so the
18910 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69   error.** code i
18920 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20  s promoted from 
18930 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62  the relatively b
18940 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55  enign [SQLITE_BU
18950 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f  SY] to.** the mo
18960 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54  re severe [SQLIT
18970 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
18980 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63  .  ^This error c
18990 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a  ode promotion.**
189a0 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d   forces an autom
189b0 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66  atic rollback of
189c0 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53   the changes.  S
189d0 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65  ee the.** <a hre
189e0 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69  f="/cvstrac/wiki
189f0 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ?p=CorruptionFol
18a00 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22  lowingBusyError"
18a10 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46  >.** CorruptionF
18a20 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
18a30 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20  r</a> wiki page 
18a40 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e  for a discussion
18a50 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20   of why.** this 
18a60 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a  is important..**
18a70 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
18a80 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
18a90 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65   busy handler de
18aa0 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a  fined for each.*
18ab0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
18ac0 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e  ection].  Settin
18ad0 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
18ae0 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a  dler clears any.
18af0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
18b00 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e  t handler.)^  ^N
18b10 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67  ote that calling
18b20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
18b30 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c  imeout()].** wil
18b40 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c  l also set or cl
18b50 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e  ear the busy han
18b60 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  dler..**.** The 
18b70 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68  busy callback sh
18b80 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e  ould not take an
18b90 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20  y actions which 
18ba0 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61  modify the.** da
18bb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18bc0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
18bd0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
18be0 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f    Any such actio
18bf0 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20  ns.** result in 
18c00 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
18c10 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73  or..** .** A bus
18c20 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  y handler must n
18c30 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ot close the dat
18c40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18c50 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64  .** or [prepared
18c60 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
18c70 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
18c80 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e  y handler..*/.in
18c90 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
18ca0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
18cb0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e   int(*)(void*,in
18cc0 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  t), void*);../*.
18cd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
18ce0 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a   A Busy Timeout.
18cf0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
18d00 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
18d10 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
18d20 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
18d30 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20   that sleeps.** 
18d40 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20  for a specified 
18d50 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77  amount of time w
18d60 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c  hen a table is l
18d70 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e  ocked.  ^The han
18d80 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65  dler.** will sle
18d90 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ep multiple time
18da0 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74  s until at least
18db0 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
18dc0 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a  ds of sleeping.*
18dd0 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74  * have accumulat
18de0 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c  ed.  ^After at l
18df0 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
18e00 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
18e10 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
18e20 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
18e30 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
18e40 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
18e50 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
18e60 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
18e70 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
18e80 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
18e90 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
18ea0 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65  h an argument le
18eb0 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
18ec0 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e   to zero.** turn
18ed0 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68  s off all busy h
18ee0 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  andlers..**.** ^
18ef0 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
18f00 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
18f10 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70   handler for a p
18f20 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
18f30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18f40 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e  n] any any given
18f50 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f   moment.  If ano
18f60 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
18f70 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64  r.** was defined
18f80 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65    (using [sqlite
18f90 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
18fa0 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
18fb0 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
18fc0 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
18fd0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
18fe0 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e  cleared.)^.*/.in
18ff0 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
19000 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
19010 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
19020 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
19030 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
19040 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
19050 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ies.**.** This i
19060 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72  s a legacy inter
19070 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65  face that is pre
19080 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77  served for backw
19090 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
190a0 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68  ty..** Use of th
190b0 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
190c0 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e  not recommended.
190d0 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f  .**.** Definitio
190e0 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74  n: A <b>result t
190f0 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f  able</b> is memo
19100 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ry data structur
19110 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65  e created by the
19120 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
19130 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66  _table()] interf
19140 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74  ace.  A result t
19150 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65  able records the
19160 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65  .** complete que
19170 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  ry results from 
19180 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72  one or more quer
19190 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ies..**.** The t
191a0 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c  able conceptuall
191b0 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f  y has a number o
191c0 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d  f rows and colum
191d0 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73  ns.  But.** thes
191e0 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f  e numbers are no
191f0 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65  t part of the re
19200 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c  sult table itsel
19210 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d  f.  These.** num
19220 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65  bers are obtaine
19230 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c  d separately.  L
19240 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62  et N be the numb
19250 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e  er of rows.** an
19260 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65  d M be the numbe
19270 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a  r of columns..**
19280 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
19290 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  le is an array o
192a0 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  f pointers to ze
192b0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
192c0 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
192d0 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
192e0 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
192f0 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69  e array.  The fi
19300 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70  rst M pointers p
19310 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d  oint.** to zero-
19320 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
19330 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e  gs that  contain
19340 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
19350 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68  e columns..** Th
19360 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72  e remaining entr
19370 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f  ies all point to
19380 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20   query results. 
19390 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73   NULL values res
193a0 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70  ult.** in NULL p
193b0 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74  ointers.  All ot
193c0 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69  her values are i
193d0 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65  n their UTF-8 ze
193e0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
193f0 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e   string represen
19400 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e  tation as return
19410 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
19420 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
19430 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
19440 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73  ble might consis
19450 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  t of one or more
19460 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
19470 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ons..** It is no
19480 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61  t safe to pass a
19490 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69   result table di
194a0 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74  rectly to [sqlit
194b0 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41  e3_free()]..** A
194c0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68   result table sh
194d0 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61  ould be dealloca
194e0 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
194f0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
19500 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20  ..**.** ^(As an 
19510 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
19520 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
19530 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
19540 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
19550 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
19560 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
19570 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
19580 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
19590 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
195a0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
195b0 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
195c0 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
195d0 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
195e0 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
195f0 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
19600 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
19610 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
19620 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
19630 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
19640 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
19650 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
19660 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
19670 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
19680 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
19690 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
196a0 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
196b0 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
196c0 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
196d0 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
196e0 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
196f0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
19700 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
19710 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
19720 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
19730 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
19740 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
19750 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
19760 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
19770 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
19780 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
19790 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
197a0 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
197b0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
197c0 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
197d0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
197e0 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
197f0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
19800 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
19810 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
19820 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
19830 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
19840 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
19850 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
19860 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
19870 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
19880 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
19890 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
198a0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
198b0 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
198c0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  2nd parameter an
198d0 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  d returns a resu
198e0 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a  lt table to the.
198f0 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e  ** pointer given
19900 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61   in its 3rd para
19910 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  meter..**.** Aft
19920 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
19930 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
19940 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20  with the result 
19950 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74  from sqlite3_get
19960 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20  _table(),.** it 
19970 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65  must pass the re
19980 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74  sult table point
19990 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  er to sqlite3_fr
199a0 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
199b0 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73  der to.** releas
199c0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
199d0 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20  t was malloced. 
199e0 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
199f0 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  way the.** [sqli
19a00 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
19a10 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
19a20 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
19a30 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
19a40 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
19a50 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
19a60 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
19a70 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a  directly.  Only.
19a80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
19a90 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c  _table()] is abl
19aa0 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65  e to release the
19ab0 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79   memory properly
19ac0 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a   and safely..**.
19ad0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
19ae0 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72  et_table() inter
19af0 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  face is implemen
19b00 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72  ted as a wrapper
19b10 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
19b20 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68  te3_exec()].  Th
19b30 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
19b40 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  ble() routine do
19b50 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  es not have acce
19b60 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74  ss.** to any int
19b70 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63  ernal data struc
19b80 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  tures of SQLite.
19b90 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74    It uses only t
19ba0 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74  he public.** int
19bb0 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68  erface defined h
19bc0 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65  ere.  As a conse
19bd0 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74  quence, errors t
19be0 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65  hat occur in the
19bf0 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65  .** wrapper laye
19c00 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  r outside of the
19c10 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74   internal [sqlit
19c20 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20  e3_exec()] call 
19c30 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65  are not.** refle
19c40 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65  cted in subseque
19c50 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
19c60 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
19c70 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  or.** [sqlite3_e
19c80 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  rrmsg()]..*/.int
19c90 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
19ca0 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  le(.  sqlite3 *d
19cb0 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41  b,          /* A
19cc0 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
19cd0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
19ce0 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51  *zSql,     /* SQ
19cf0 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  L to be evaluate
19d00 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70  d */.  char ***p
19d10 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20  azResult,    /* 
19d20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71  Results of the q
19d30 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  uery */.  int *p
19d40 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20  nRow,           
19d50 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
19d60 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e  ult rows written
19d70 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   here */.  int *
19d80 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20  pnColumn,       
19d90 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
19da0 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69  sult columns wri
19db0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63  tten here */.  c
19dc0 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20  har **pzErrmsg  
19dd0 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
19de0 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
19df0 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  /.);.void sqlite
19e00 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61  3_free_table(cha
19e10 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a  r **result);../*
19e20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f  .** CAPI3REF: Fo
19e30 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50  rmatted String P
19e40 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e  rinting Function
19e50 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
19e60 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d  utines are work-
19e70 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70  alikes of the "p
19e80 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20  rintf()" family 
19e90 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  of functions.** 
19ea0 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
19eb0 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  d C library..**.
19ec0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
19ed0 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
19ee0 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
19ef0 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
19f00 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
19f10 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
19f20 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
19f30 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
19f40 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
19f50 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
19f60 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
19f70 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
19f80 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
19f90 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72  ree()].  ^Both r
19fa0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
19fb0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
19fc0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
19fd0 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  loc()] is unable
19fe0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
19ff0 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
1a000 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
1a010 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
1a020 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
1a030 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
1a040 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
1a050 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
1a060 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
1a070 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
1a080 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
1a090 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
1a0a0 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
1a0b0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
1a0c0 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
1a0d0 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
1a0e0 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
1a0f0 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
1a100 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
1a110 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
1a120 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
1a130 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
1a140 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20  intf().)^  This 
1a150 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
1a160 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
1a170 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
1a180 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
1a190 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
1a1a0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
1a1b0 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ^(Note also that
1a1c0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1a1d0 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
1a1e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
1a1f0 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
1a200 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
1a210 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
1a220 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
1a230 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29  nto the buffer.)
1a240 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ^  We admit that
1a250 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
1a260 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
1a270 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
1a280 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
1a290 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
1a2a0 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
1a2b0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
1a2c0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
1a2d0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
1a2e0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
1a2f0 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
1a300 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20  .**.** ^As long 
1a310 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
1a320 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
1a330 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
1a340 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
1a350 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
1a360 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
1a370 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
1a380 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ted.  ^The first
1a390 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
1a3a0 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
1a3b0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
1a3c0 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
1a3d0 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
1a3e0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
1a3f0 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
1a400 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
1a410 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
1a420 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
1a430 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
1a440 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1a450 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72  e3_vsnprintf() r
1a460 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61  outine is a vara
1a470 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73  rgs version of s
1a480 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1a490 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )..**.** These r
1a4a0 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
1a4b0 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
1a4c0 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
1a4d0 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
1a4e0 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
1a4f0 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
1a500 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
1a510 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
1a520 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
1a530 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
1a540 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
1a550 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
1a560 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e  e "%q", "%Q", an
1a570 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a  d "%z" options..
1a580 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f  **.** ^(The %q o
1a590 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1a5a0 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73   %s in that it s
1a5b0 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c  ubstitutes a nul
1a5c0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
1a5d0 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
1a5e0 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
1a5f0 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
1a600 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
1a610 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
1a620 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
1a630 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
1a640 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42  ng literal.)^  B
1a650 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20  y doubling each 
1a660 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65  '\''.** characte
1a670 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61  r it escapes tha
1a680 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20  t character and 
1a690 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20  allows it to be 
1a6a0 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a  inserted into.**
1a6b0 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a   the string..**.
1a6c0 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
1a6d0 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e  assume the strin
1a6e0 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74  g variable zText
1a6f0 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61   contains text a
1a700 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1a710 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1a720 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65  e>.**  char *zTe
1a730 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70  xt = "It's a hap
1a740 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70  py day!";.** </p
1a750 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1a760 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75  .**.** One can u
1a770 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20  se this text in 
1a780 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1a790 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1a7a0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1a7b0 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1a7c0 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
1a7d0 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
1a7e0 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
1a7f0 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a  '%q')", zText);.
1a800 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
1a810 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
1a820 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
1a830 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
1a840 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1a850 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  te>.**.** Becaus
1a860 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20  e the %q format 
1a870 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20  string is used, 
1a880 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74  the '\'' charact
1a890 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69  er in zText.** i
1a8a0 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68  s escaped and th
1a8b0 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20  e SQL generated 
1a8c0 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
1a8d0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1a8e0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
1a8f0 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
1a900 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61  LUES('It''s a ha
1a910 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f  ppy day!').** </
1a920 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1a930 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  >.**.** This is 
1a940 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65  correct.  Had we
1a950 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64   used %s instead
1a960 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65   of %q, the gene
1a970 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75  rated SQL.** wou
1a980 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c  ld have looked l
1a990 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
1a9a0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1a9b0 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
1a9c0 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
1a9d0 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  'It's a happy da
1a9e0 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  y!');.** </pre><
1a9f0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1aa00 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65  ** This second e
1aa10 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c  xample is an SQL
1aa20 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20   syntax error.  
1aa30 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c  As a general rul
1aa40 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20  e you should.** 
1aa50 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e  always use %q in
1aa60 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e  stead of %s when
1aa70 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20   inserting text 
1aa80 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  into a string li
1aa90 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  teral..**.** ^(T
1aaa0 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72  he %Q option wor
1aab0 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70  ks like %q excep
1aac0 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73  t it also adds s
1aad0 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f  ingle quotes aro
1aae0 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69  und.** the outsi
1aaf0 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20  de of the total 
1ab00 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f  string.  Additio
1ab10 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61  nally, if the pa
1ab20 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a  rameter in the.*
1ab30 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20  * argument list 
1ab40 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1ab50 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65  r, %Q substitute
1ab60 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c  s the text "NULL
1ab70 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69  " (without.** si
1ab80 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20  ngle quotes).)^ 
1ab90 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65   So, for example
1aba0 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a  , one could say:
1abb0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1abc0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1abd0 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
1abe0 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
1abf0 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
1ac00 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29  UES(%Q)", zText)
1ac10 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1ac20 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1ac30 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1ac40 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1ac50 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1ac60 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
1ac70 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20  code above will 
1ac80 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74  render a correct
1ac90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
1aca0 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61  n the zSQL.** va
1acb0 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74  riable even if t
1acc0 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c  he zText variabl
1acd0 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e is a NULL poin
1ace0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ter..**.** ^(The
1acf0 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
1ad00 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1ad10 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68  ke "%s" but with
1ad20 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
1ad30 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
1ad40 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
1ad50 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
1ad60 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
1ad70 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
1ad80 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
1ad90 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
1ada0 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73  ng.)^.*/.char *s
1adb0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
1adc0 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
1add0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
1ade0 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1adf0 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63  ar*, va_list);.c
1ae00 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
1ae10 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
1ae20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
1ae30 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1ae40 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  _vsnprintf(int,c
1ae50 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1ae60 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a  , va_list);../*.
1ae70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
1ae80 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
1ae90 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54  ubsystem.**.** T
1aea0 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
1aeb0 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
1aec0 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
1aed0 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
1aee0 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
1aef0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
1af00 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
1af10 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
1af20 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
1af30 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
1af40 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
1af50 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
1af60 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
1af70 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
1af80 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
1af90 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
1afa0 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
1afb0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1afc0 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
1afd0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1afe0 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
1aff0 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
1b000 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
1b010 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
1b020 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
1b030 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
1b040 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
1b050 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
1b060 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
1b070 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
1b080 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1b090 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d  .  ^If the param
1b0a0 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
1b0b0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
1b0c0 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
1b0d0 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
1b0e0 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
1b0f0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
1b100 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  r..**.** ^Callin
1b110 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
1b120 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
1b130 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
1b140 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
1b150 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
1b160 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1b170 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65  releases that me
1b180 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20  mory so.** that 
1b190 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73  it might be reus
1b1a0 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
1b1b0 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  3_free() routine
1b1c0 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69   is.** a no-op i
1b1d0 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  f is called with
1b1e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1b1f0 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c    Passing a NULL
1b200 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73   pointer.** to s
1b210 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
1b220 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65   harmless.  Afte
1b230 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d  r being freed, m
1b240 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20  emory.** should 
1b250 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20  neither be read 
1b260 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76  nor written.  Ev
1b270 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69  en reading previ
1b280 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d  ously freed.** m
1b290 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75  emory might resu
1b2a0 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
1b2b0 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
1b2c0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1b2d0 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72  ..** Memory corr
1b2e0 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e  uption, a segmen
1b2f0 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72  tation fault, or
1b300 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
1b310 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73  ror.** might res
1b320 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66  ult if sqlite3_f
1b330 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ree() is called 
1b340 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
1b350 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
1b360 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64  was not obtained
1b370 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
1b380 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
1b390 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a  3_realloc()..**.
1b3a0 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
1b3b0 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72  _realloc() inter
1b3c0 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
1b3d0 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69   resize a.** pri
1b3e0 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  or memory alloca
1b3f0 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65  tion to be at le
1b400 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65  ast N bytes, whe
1b410 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73  re N is the.** s
1b420 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
1b430 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c    The memory all
1b440 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65  ocation to be re
1b450 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72  sized is the fir
1b460 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  st.** parameter.
1b470 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73  )^ ^ If the firs
1b480 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
1b490 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1b4a0 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
1b4b0 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
1b4c0 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
1b4d0 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
1b4e0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1b4f0 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20  c(N) where N is 
1b500 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1b510 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1b520 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49  realloc()..** ^I
1b530 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  f the second par
1b540 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1b550 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a  3_realloc() is z
1b560 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69  ero or.** negati
1b570 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ve then the beha
1b580 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20  vior is exactly 
1b590 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c  the same as call
1b5a0 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  ing.** sqlite3_f
1b5b0 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69  ree(P) where P i
1b5c0 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
1b5d0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1b5e0 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e  _realloc()..** ^
1b5f0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1b600 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
1b610 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
1b620 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
1b630 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1b640 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
1b650 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20  L if sufficient 
1b660 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69  memory is unavai
1b670 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
1b680 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
1b690 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1b6a0 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
1b6b0 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
1b6c0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1b6d0 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
1b6e0 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
1b6f0 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
1b700 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1b710 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  e3_realloc() and
1b720 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1b730 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a  ation is freed..
1b740 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72  ** ^If sqlite3_r
1b750 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
1b760 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
1b770 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1b780 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64  .** is not freed
1b790 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
1b7a0 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
1b7b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1b7c0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
1b7d0 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77  lloc().** is alw
1b7e0 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
1b7f0 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
1b800 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74  e boundary, or t
1b810 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f  o a.** 4 byte bo
1b820 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53  undary if the [S
1b830 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49  QLITE_4_BYTE_ALI
1b840 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d  GNED_MALLOC] com
1b850 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
1b860 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
1b870 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72  ** In SQLite ver
1b880 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33  sion 3.5.0 and 3
1b890 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73  .5.1, it was pos
1b8a0 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a  sible to define.
1b8b0 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  ** the SQLITE_OM
1b8c0 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
1b8d0 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64  TION which would
1b8e0 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74   cause the built
1b8f0 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  -in.** implement
1b900 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
1b910 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d  outines to be om
1b920 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70  itted.  That cap
1b930 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f  ability.** is no
1b940 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64   longer provided
1b950 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e  .  Only built-in
1b960 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
1b970 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a  rs can be used..
1b980 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53  **.** Prior to S
1b990 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1b9a0 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77  7.10, the Window
1b9b0 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
1b9c0 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  ayer called.** t
1b9d0 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
1b9e0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69  () and free() di
1b9f0 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76  rectly when conv
1ba00 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61  erting.** filena
1ba10 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20  mes between the 
1ba20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75  UTF-8 encoding u
1ba30 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  sed by SQLite.**
1ba40 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69   and whatever fi
1ba50 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20  lename encoding 
1ba60 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70  is used by the p
1ba70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77  articular Window
1ba80 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f  s.** installatio
1ba90 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  n.  Memory alloc
1baa0 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72  ation errors wer
1bab0 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
1bac0 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70  ** they were rep
1bad0 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53  orted back as [S
1bae0 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
1baf0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
1bb00 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e  ERR] rather than
1bb10 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
1bb20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  .**.** The point
1bb30 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
1bb40 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1bb50 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1bb60 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  alloc()].** must
1bb70 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20   be either NULL 
1bb80 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73  or else pointers
1bb90 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
1bba0 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61   prior.** invoca
1bbb0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
1bbc0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
1bbd0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1bbe0 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e  ] that have.** n
1bbf0 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65  ot yet been rele
1bc00 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ased..**.** The 
1bc10 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
1bc20 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69   not read or wri
1bc30 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a  te any part of.*
1bc40 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  * a block of mem
1bc50 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73  ory after it has
1bc60 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75   been released u
1bc70 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
1bc80 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c  _free()] or [sql
1bc90 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e  ite3_realloc()].
1bca0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
1bcb0 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76  3_malloc(int);.v
1bcc0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
1bcd0 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
1bce0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
1bcf0 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  ree(void*);../*.
1bd00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
1bd10 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74  ory Allocator St
1bd20 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53  atistics.**.** S
1bd30 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
1bd40 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
1bd50 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
1bd60 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
1bd70 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
1bd80 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
1bd90 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
1bda0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1bdb0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
1bdc0 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
1bdd0 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
1bde0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
1bdf0 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
1be00 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
1be10 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75  mory_used()] rou
1be20 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
1be30 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
1be40 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75  .** of memory cu
1be50 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64  rrently outstand
1be60 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75  ing (malloced bu
1be70 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a  t not freed)..**
1be80 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1be90 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1bea0 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1beb0 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  ns the maximum.*
1bec0 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69  * value of [sqli
1bed0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1bee0 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67  )] since the hig
1bef0 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
1bf00 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20  was last reset. 
1bf10 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
1bf20 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1bf30 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1bf40 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1bf50 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1bf60 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79  r()] include any
1bf70 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64   overhead.** add
1bf80 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20  ed by SQLite in 
1bf90 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  its implementati
1bfa0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
1bfb0 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74  alloc()],.** but
1bfc0 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64   not overhead ad
1bfd0 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75  ded by the any u
1bfe0 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d  nderlying system
1bff0 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74   library.** rout
1c000 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74  ines that [sqlit
1c010 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79  e3_malloc()] may
1c020 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   call..**.** ^Th
1c030 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61  e memory high-wa
1c040 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65  ter mark is rese
1c050 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74  t to the current
1c060 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71   value of.** [sq
1c070 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1c080 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  d()] if and only
1c090 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1c0a0 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
1c0b0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1c0c0 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e  r()] is true.  ^
1c0d0 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
1c0e0 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
1c0f0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1c100 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69  er(1)] is the hi
1c110 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1c120 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65   prior to the re
1c130 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  set..*/.sqlite3_
1c140 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
1c150 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b  mory_used(void);
1c160 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
1c170 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1c180 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65  ghwater(int rese
1c190 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  tFlag);../*.** C
1c1a0 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d  API3REF: Pseudo-
1c1b0 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65  Random Number Ge
1c1c0 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51  nerator.**.** SQ
1c1d0 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20  Lite contains a 
1c1e0 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65  high-quality pse
1c1f0 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65  udo-random numbe
1c200 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e  r generator (PRN
1c210 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65  G) used to.** se
1c220 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57  lect random [ROW
1c230 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65  ID | ROWIDs] whe
1c240 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20  n inserting new 
1c250 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74  records into a t
1c260 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72  able that.** alr
1c270 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61  eady uses the la
1c280 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b  rgest possible [
1c290 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e  ROWID].  The PRN
1c2a0 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66  G is also used f
1c2b0 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d  or.** the build-
1c2c0 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20  in random() and 
1c2d0 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c  randomblob() SQL
1c2e0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69   functions.  Thi
1c2f0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
1c300 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  ws.** applicatio
1c310 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ns to access the
1c320 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f   same PRNG for o
1c330 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a  ther purposes..*
1c340 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  *.** ^A call to 
1c350 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  this routine sto
1c360 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72  res N bytes of r
1c370 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62  andomness into b
1c380 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e  uffer P..**.** ^
1c390 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
1c3a0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69  his routine is i
1c3b0 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69  nvoked (either i
1c3c0 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a  nternally or by.
1c3d0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
1c3e0 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20  on) the PRNG is 
1c3f0 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e  seeded using ran
1c400 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
1c410 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61  .** from the xRa
1c420 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
1c430 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
1c440 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1c450 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20  ect..** ^On all 
1c460 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
1c470 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75  ations, the pseu
1c480 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
1c490 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
1c4a0 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
1c4b0 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
1c4c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
1c4d0 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
1c4e0 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69  * method..*/.voi
1c4f0 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
1c500 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
1c510 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
1c520 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
1c530 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
1c540 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  n Callbacks.**.*
1c550 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
1c560 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74  registers an aut
1c570 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1c580 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
1c590 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
1c5a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70  connection], sup
1c5b0 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  plied in the fir
1c5c0 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  st argument..** 
1c5d0 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
1c5e0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1c5f0 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65  ked as SQL state
1c600 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20  ments are being 
1c610 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b  compiled.** by [
1c620 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1c630 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
1c640 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ts [sqlite3_prep
1c650 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  are_v2()],.** [s
1c660 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1c670 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1c680 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
1c690 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a  .  ^At various.*
1c6a0 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20  * points during 
1c6b0 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  the compilation 
1c6c0 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69  process, as logi
1c6d0 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74  c is being creat
1c6e0 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d  ed.** to perform
1c6f0 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73   various actions
1c700 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  , the authorizer
1c710 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1c720 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69  oked to.** see i
1c730 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20  f those actions 
1c740 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54  are allowed.  ^T
1c750 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1c760 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a  llback should.**
1c770 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1c780 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65  OK] to allow the
1c790 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45   action, [SQLITE
1c7a0 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61  _IGNORE] to disa
1c7b0 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63  llow the.** spec
1c7c0 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20  ific action but 
1c7d0 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74  allow the SQL st
1c7e0 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69  atement to conti
1c7f0 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  nue to be.** com
1c800 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54  piled, or [SQLIT
1c810 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65  E_DENY] to cause
1c820 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20   the entire SQL 
1c830 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a  statement to be.
1c840 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68  ** rejected with
1c850 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20   an error.  ^If 
1c860 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1c870 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
1c880 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ** any value oth
1c890 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1c8a0 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45  IGNORE], [SQLITE
1c8b0 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  _OK], or [SQLITE
1c8c0 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74  _DENY].** then t
1c8d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
1c8e0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
1c8f0 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
1c900 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74  t triggered.** t
1c910 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  he authorizer wi
1c920 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
1c930 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
1c940 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61  *.** When the ca
1c950 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1c960 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74  SQLITE_OK], that
1c970 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61   means the opera
1c980 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65  tion.** requeste
1c990 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20  d is ok.  ^When 
1c9a0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1c9b0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  urns [SQLITE_DEN
1c9c0 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  Y], the.** [sqli
1c9d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1c9e0 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
1c9f0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
1ca00 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f  red the.** autho
1ca10 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
1ca20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
1ca30 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67  ssage explaining
1ca40 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20   that.** access 
1ca50 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a  is denied. .**.*
1ca60 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
1ca70 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1ca80 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1ca90 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
1caa0 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
1cab0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
1cac0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1cad0 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
1cae0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
1caf0 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
1cb00 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
1cb10 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f  integer [SQLITE_
1cb20 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f  COPY | action co
1cb30 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69  de] that specifi
1cb40 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63  es.** the partic
1cb50 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62  ular action to b
1cb60 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54  e authorized. ^T
1cb70 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68  he third through
1cb80 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
1cb90 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  s.** to the call
1cba0 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65  back are zero-te
1cbb0 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
1cbc0 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64   that contain ad
1cbd0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61  ditional.** deta
1cbe0 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
1cbf0 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
1cc00 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rized..**.** ^If
1cc10 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
1cc20 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44   is [SQLITE_READ
1cc30 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c  ].** and the cal
1cc40 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1cc50 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
1cc60 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  en the.** [prepa
1cc70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73  red statement] s
1cc80 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73  tatement is cons
1cc90 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74  tructed to subst
1cca0 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20  itute.** a NULL 
1ccb0 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f  value in place o
1ccc0 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
1ccd0 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  mn that would ha
1cce0 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20  ve.** been read 
1ccf0 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
1cd00 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
1cd10 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  .  The [SQLITE_I
1cd20 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e  GNORE].** return
1cd30 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1cd40 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65  deny an untruste
1cd50 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f  d user access to
1cd60 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63   individual.** c
1cd70 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c  olumns of a tabl
1cd80 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  e..** ^If the ac
1cd90 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
1cda0 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64  LITE_DELETE] and
1cdb0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1cdc0 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
1cdd0 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
1cde0 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61  e [DELETE] opera
1cdf0 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75  tion proceeds bu
1ce00 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61  t the.** [trunca
1ce10 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d  te optimization]
1ce20 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64   is disabled and
1ce30 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65   all rows are de
1ce40 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c  leted individual
1ce50 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74  ly..**.** An aut
1ce60 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20  horizer is used 
1ce70 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  when [sqlite3_pr
1ce80 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e  epare | preparin
1ce90 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  g].** SQL statem
1cea0 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74  ents from an unt
1ceb0 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74  rusted source, t
1cec0 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  o ensure that th
1ced0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
1cee0 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74  .** do not try t
1cef0 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68  o access data th
1cf00 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77  ey are not allow
1cf10 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68  ed to see, or th
1cf20 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
1cf30 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65  * try to execute
1cf40 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65   malicious state
1cf50 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67  ments that damag
1cf60 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  e the database. 
1cf70 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
1cf80 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
1cf90 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72  may allow a user
1cfa0 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72   to enter arbitr
1cfb0 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69  ary.** SQL queri
1cfc0 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f  es for evaluatio
1cfd0 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e  n by a database.
1cfe0 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63    But the applic
1cff0 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ation does.** no
1d000 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20  t want the user 
1d010 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61  to be able to ma
1d020 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61  ke arbitrary cha
1d030 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  nges to the.** d
1d040 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74  atabase.  An aut
1d050 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68  horizer could th
1d060 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61  en be put in pla
1d070 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20  ce while the.** 
1d080 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c  user-entered SQL
1d090 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74   is being [sqlit
1d0a0 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
1d0b0 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64  pared] that.** d
1d0c0 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68  isallows everyth
1d0d0 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45  ing except [SELE
1d0e0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  CT] statements..
1d0f0 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
1d100 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20  ns that need to 
1d110 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d  process SQL from
1d120 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
1d130 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f  es.** might also
1d140 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69   consider loweri
1d150 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69  ng resource limi
1d160 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ts using [sqlite
1d170 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e  3_limit()].** an
1d180 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62  d limiting datab
1d190 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74  ase size using t
1d1a0 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  he [max_page_cou
1d1b0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20  nt] [PRAGMA].** 
1d1c0 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75  in addition to u
1d1d0 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a  sing an authoriz
1d1e0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79  er..**.** ^(Only
1d1f0 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
1d200 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
1d210 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
1d220 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1d230 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
1d240 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
1d250 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1d260 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
1d270 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
1d280 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65  )^  ^Disable the
1d290 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69   authorizer by i
1d2a0 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c  nstalling a NULL
1d2b0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68   callback..** Th
1d2c0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  e authorizer is 
1d2d0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
1d2e0 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ult..**.** The a
1d2f0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1d300 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
1d310 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
1d320 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
1d330 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d340 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
1d350 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1d360 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74  callback..** Not
1d370 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
1d380 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
1d390 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
1d3a0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
1d3b0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
1d3c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
1d3d0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
1d3e0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
1d3f0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
1d400 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  * ^When [sqlite3
1d410 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
1d420 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72  s used to prepar
1d430 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  e a statement, t
1d440 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  he.** statement 
1d450 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70  might be re-prep
1d460 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c  ared during [sql
1d470 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65  ite3_step()] due
1d480 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61   to a .** schema
1d490 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c   change.  Hence,
1d4a0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1d4b0 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74   should ensure t
1d4c0 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  hat the.** corre
1d4d0 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ct authorizer ca
1d4e0 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69  llback remains i
1d4f0 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74  n place during t
1d500 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
1d510 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65  ()]..**.** ^Note
1d520 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
1d530 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1d540 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
1d550 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ring.** [sqlite3
1d560 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
1d570 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
1d580 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
1d590 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
1d5a0 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
1d5b0 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
1d5c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
1d5d0 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74   unless.** as st
1d5e0 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76  ated in the prev
1d5f0 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20  ious paragraph, 
1d600 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
1d610 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65  nvokes.** sqlite
1d620 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74  3_prepare_v2() t
1d630 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74  o reprepare a st
1d640 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20  atement after a 
1d650 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a  schema change..*
1d660 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65  /.int sqlite3_se
1d670 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20  t_authorizer(.  
1d680 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20  sqlite3*,.  int 
1d690 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69  (*xAuth)(void*,i
1d6a0 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  nt,const char*,c
1d6b0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1d6c0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
1d6d0 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73  r*),.  void *pUs
1d6e0 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  erData.);../*.**
1d6f0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
1d700 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64  rizer Return Cod
1d710 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
1d720 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1d730 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
1d740 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
1d750 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74  ion] must.** ret
1d760 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49  urn either [SQLI
1d770 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66  TE_OK] or one of
1d780 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74   these two const
1d790 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  ants in order.**
1d7a0 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74   to signal SQLit
1d7b0 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  e whether or not
1d7c0 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70   the action is p
1d7d0 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74  ermitted.  See t
1d7e0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
1d7f0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
1d800 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d  authorizer docum
1d810 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64  entation] for ad
1d820 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
1d830 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e  rmation..**.** N
1d840 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f  ote that SQLITE_
1d850 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75  IGNORE is also u
1d860 73 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45  sed as a [SQLITE
1d870 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75  _ROLLBACK | retu
1d880 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d  rn code].** from
1d890 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74   the [sqlite3_vt
1d8a0 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
1d8b0 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
1d8c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1d8d0 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
1d8e0 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
1d8f0 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
1d900 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
1d910 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
1d920 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
1d930 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
1d940 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
1d950 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
1d960 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
1d970 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
1d980 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
1d990 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1d9a0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
1d9b0 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
1d9c0 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
1d9d0 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
1d9e0 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
1d9f0 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
1da00 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
1da10 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
1da20 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
1da30 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
1da40 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
1da50 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
1da60 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
1da70 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
1da80 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
1da90 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
1daa0 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
1dab0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
1dac0 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
1dad0 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
1dae0 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
1daf0 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
1db00 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
1db10 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
1db20 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
1db30 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
1db40 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
1db50 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
1db60 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
1db70 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
1db80 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
1db90 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
1dba0 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
1dbb0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
1dbc0 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
1dbd0 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
1dbe0 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
1dbf0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1dc00 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1dc10 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
1dc20 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
1dc30 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
1dc40 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
1dc50 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
1dc60 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1dc70 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
1dc80 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
1dc90 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
1dca0 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
1dcb0 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
1dcc0 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
1dcd0 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
1dce0 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
1dcf0 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
1dd00 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
1dd10 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
1dd20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1dd30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1dd40 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
1dd50 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
1dd60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
1dd70 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1dd80 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
1dd90 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
1dda0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1ddb0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1ddc0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1ddd0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
1dde0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1ddf0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1de00 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1de10 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1de20 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
1de30 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1de40 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1de50 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1de60 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1de70 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
1de80 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1de90 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1dea0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1deb0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1dec0 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
1ded0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1dee0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1def0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1df00 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1df10 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
1df20 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1df30 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1df40 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1df50 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
1df60 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
1df70 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1df80 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1df90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1dfa0 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
1dfb0 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
1dfc0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1dfd0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1dfe0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1dff0 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
1e000 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
1e010 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1e020 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1e030 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e040 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
1e050 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
1e060 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1e070 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1e080 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e090 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
1e0a0 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
1e0b0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1e0c0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1e0d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1e0e0 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
1e0f0 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
1e100 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1e110 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1e120 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1e130 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
1e140 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
1e150 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1e160 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1e170 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1e180 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
1e190 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
1e1a0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1e1b0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1e1c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1e1d0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
1e1e0 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
1e1f0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1e200 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1e210 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1e220 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
1e230 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
1e240 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1e250 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1e260 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
1e270 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
1e280 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
1e290 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1e2a0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1e2b0 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
1e2c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
1e2d0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1e2e0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1e2f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1e300 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
1e310 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
1e320 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
1e330 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
1e340 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
1e350 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
1e360 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
1e370 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1e380 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
1e390 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e3a0 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
1e3b0 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
1e3c0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
1e3d0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1e3e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e3f0 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
1e400 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
1e410 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
1e420 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1e430 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e440 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
1e450 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
1e460 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1e470 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
1e480 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e490 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
1e4a0 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
1e4b0 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
1e4c0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1e4d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e4e0 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
1e4f0 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
1e500 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
1e510 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1e520 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e530 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
1e540 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
1e550 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
1e560 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1e570 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e580 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
1e590 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
1e5a0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
1e5b0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1e5c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1e5d0 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
1e5e0 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
1e5f0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1e600 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1e610 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1e620 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
1e630 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
1e640 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
1e650 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
1e660 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1e670 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
1e680 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
1e690 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
1e6a0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1e6b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
1e6c0 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
1e6d0 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
1e6e0 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
1e6f0 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
1e700 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
1e710 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
1e720 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
1e730 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
1e740 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
1e750 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
1e760 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1e770 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
1e780 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   used */../*.** 
1e790 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e  CAPI3REF: Tracin
1e7a0 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20  g And Profiling 
1e7b0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1e7c0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1e7d0 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
1e7e0 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
1e7f0 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a  can be used for.
1e800 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70  ** tracing and p
1e810 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65  rofiling the exe
1e820 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74  cution of SQL st
1e830 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
1e840 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
1e850 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
1e860 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61  d by sqlite3_tra
1e870 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ce() is invoked 
1e880 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69  at.** various ti
1e890 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20  mes when an SQL 
1e8a0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69  statement is bei
1e8b0 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74  ng run by [sqlit
1e8c0 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e  e3_step()]..** ^
1e8d0 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
1e8e0 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e() callback is 
1e8f0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55  invoked with a U
1e900 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
1e910 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61  f the.** SQL sta
1e920 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74  tement text as t
1e930 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
1e940 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
1e950 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69  ing..** ^(Additi
1e960 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61  onal sqlite3_tra
1e970 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d  ce() callbacks m
1e980 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73  ight occur.** as
1e990 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20   each triggered 
1e9a0 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
1e9b0 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
1e9c0 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
1e9d0 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
1e9e0 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
1e9f0 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
1ea00 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e  s the trigger.)^
1ea10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
1ea20 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
1ea30 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
1ea40 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
1ea50 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
1ea60 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
1ea70 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68  t finishes.  ^Th
1ea80 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
1ea90 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
1eaa0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
1eab0 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
1eac0 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
1ead0 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
1eae0 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
1eaf0 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
1eb00 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70   to run.  ^The p
1eb10 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a  rofile callback.
1eb20 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e  ** time is in un
1eb30 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  its of nanosecon
1eb40 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  ds, however the 
1eb50 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
1eb60 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c  tation.** is onl
1eb70 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c  y capable of mil
1eb80 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74  lisecond resolut
1eb90 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c  ion so the six l
1eba0 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  east significant
1ebb0 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68  .** digits in th
1ebc0 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69  e time are meani
1ebd0 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20  ngless.  Future 
1ebe0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1ebf0 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76  te.** might prov
1ec00 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f  ide greater reso
1ec10 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72  lution on the pr
1ec20 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  ofiler callback.
1ec30 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
1ec40 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74  _profile() funct
1ec50 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ion is considere
1ec60 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  d experimental a
1ec70 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74  nd is.** subject
1ec80 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75   to change in fu
1ec90 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
1eca0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64   SQLite..*/.void
1ecb0 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
1ecc0 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
1ecd0 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
1ece0 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
1ecf0 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  *);.SQLITE_EXPER
1ed00 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71  IMENTAL void *sq
1ed10 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
1ed20 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
1ed30 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
1ed40 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
1ed50 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
1ed60 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1ed70 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
1ed80 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a  gress Callbacks.
1ed90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1eda0 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1edb0 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74  ler(D,N,X,P) int
1edc0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
1edd0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  e callback.** fu
1ede0 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69  nction X to be i
1edf0 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
1ee00 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
1ee10 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
1ee20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
1ee30 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
1ee40 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tep()] and [sqli
1ee50 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
1ee60 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65   for.** database
1ee70 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
1ee80 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
1ee90 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
1eea0 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
1eeb0 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
1eec0 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
1eed0 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ry..**.** ^The p
1eee0 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61  arameter P is pa
1eef0 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
1ef00 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
1ef10 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61  er to the .** ca
1ef20 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1ef30 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  X.  ^The paramet
1ef40 65 72 20 4e 20 69 73 20 74 68 65 20 6e 75 6d 62  er N is the numb
1ef50 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75  er of .** [virtu
1ef60 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72  al machine instr
1ef70 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72  uctions] that ar
1ef80 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77  e evaluated betw
1ef90 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a  een successive.*
1efa0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
1efb0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e   the callback X.
1efc0 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73  .**.** ^Only a s
1efd0 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68  ingle progress h
1efe0 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65  andler may be de
1eff0 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d  fined at one tim
1f000 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61  e per.** [databa
1f010 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20  se connection]; 
1f020 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72  setting a new pr
1f030 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
1f040 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c  ancels the.** ol
1f050 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67  d one.  ^Setting
1f060 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20   parameter X to 
1f070 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68  NULL disables th
1f080 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1f090 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67  er..** ^The prog
1f0a0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20  ress handler is 
1f0b0 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79  also disabled by
1f0c0 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20   setting N to a 
1f0d0 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68  value less.** th
1f0e0 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  an 1..**.** ^If 
1f0f0 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
1f100 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
1f110 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
1f120 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
1f130 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
1f140 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
1f150 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
1f160 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
1f170 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
1f180 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
1f190 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
1f1a0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
1f1b0 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
1f1c0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
1f1d0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
1f1e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1f1f0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1f200 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73  oked the progres
1f210 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f  s handler..** No
1f220 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
1f230 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
1f240 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
1f250 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
1f260 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
1f270 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
1f280 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
1f290 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
1f2a0 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
1f2b0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
1f2c0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
1f2d0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20  (sqlite3*, int, 
1f2e0 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
1f2f0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1f300 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20  PI3REF: Opening 
1f310 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43  A New Database C
1f320 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onnection.**.** 
1f330 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1f340 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
1f350 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20  atabase file as 
1f360 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
1f370 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72   .** filename ar
1f380 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
1f390 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
1f3a0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
1f3b0 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
1f3c0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1f3d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1f3e0 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
1f3f0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1f400 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
1f410 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1f420 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
1f430 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
1f440 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
1f450 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
1f460 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
1f470 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
1f480 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
1f490 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
1f4a0 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
1f4b0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
1f4c0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1f4d0 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
1f4e0 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
1f4f0 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
1f500 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
1f510 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
1f520 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
1f530 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
1f540 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1f550 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
1f560 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
1f570 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
1f580 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
1f590 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
1f5a0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
1f5b0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
1f5c0 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
1f5d0 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
1f5e0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1f5f0 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
1f600 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
1f610 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
1f620 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
1f630 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
1f640 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
1f650 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
1f660 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
1f670 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
1f680 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
1f690 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
1f6a0 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  the database wil
1f6b0 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a  l be UTF-8 if.**
1f6c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1f6d0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
1f6e0 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  v2() is called a
1f6f0 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20  nd.** UTF-16 in 
1f700 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
1f710 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33  order if sqlite3
1f720 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65  _open16() is use
1f730 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  d..**.** Whether
1f740 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
1f750 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
1f760 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
1f770 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74  rces.** associat
1f780 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
1f790 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f7a0 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
1f7b0 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a  be released by.*
1f7c0 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  * passing it to 
1f7d0 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
1f7e0 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
1f7f0 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
1f800 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1f810 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74  e3_open_v2() int
1f820 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b  erface works lik
1f830 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
1f840 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
1f850 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61  it accepts two a
1f860 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65  dditional parame
1f870 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f  ters for additio
1f880 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f  nal control.** o
1f890 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61  ver the new data
1f8a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
1f8b0 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61    ^(The flags pa
1f8c0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71  rameter to.** sq
1f8d0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1f8e0 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a  can take one of.
1f8f0 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
1f900 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f   three values, o
1f910 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
1f920 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
1f930 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1f940 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
1f950 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20  PEN_FULLMUTEX], 
1f960 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
1f970 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53  REDCACHE],.** [S
1f980 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
1f990 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72  TECACHE], and/or
1f9a0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
1f9b0 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a  I] flags:)^.**.*
1f9c0 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e  * <dl>.** ^(<dt>
1f9d0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1f9e0 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  DONLY]</dt>.** <
1f9f0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1fa00 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61  is opened in rea
1fa10 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66  d-only mode.  If
1fa20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
1fa30 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64  es not.** alread
1fa40 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
1fa50 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
1fa60 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1fa70 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
1fa80 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a  EADWRITE]</dt>.*
1fa90 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
1faa0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
1fab0 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
1fac0 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
1fad0 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20  , or reading.** 
1fae0 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65  only if the file
1faf0 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
1fb00 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61  ted by the opera
1fb10 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e  ting system.  In
1fb20 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20   either.** case 
1fb30 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73  the database mus
1fb40 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  t already exist,
1fb50 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   otherwise an er
1fb60 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
1fb70 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1fb80 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
1fb90 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
1fba0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1fbb0 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
1fbc0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1fbd0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
1fbe0 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61  g and writing, a
1fbf0 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66  nd is created if
1fc00 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
1fc10 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
1fc20 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
1fc30 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
1fc40 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
1fc50 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
1fc60 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
1fc70 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  ().</dd>)^.** </
1fc80 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  dl>.**.** If the
1fc90 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
1fca0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1fcb0 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  2() is not one o
1fcc0 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
1fcd0 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
1fce0 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  e optionally com
1fcf0 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72  bined with other
1fd00 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1fd10 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49  _READONLY | SQLI
1fd20 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a  TE_OPEN_* bits].
1fd30 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
1fd40 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
1fd50 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
1fd60 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
1fd70 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
1fd80 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  et, then the dat
1fd90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1fda0 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65  .** opens in the
1fdb0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   multi-thread [t
1fdc0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
1fdd0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69  s long as the si
1fde0 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d  ngle-thread.** m
1fdf0 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ode has not been
1fe00 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
1fe10 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
1fe20 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  me.  ^If the.** 
1fe30 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
1fe40 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  LMUTEX] flag is 
1fe50 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74  set then the dat
1fe60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1fe70 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65   opens.** in the
1fe80 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
1fe90 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c  eading mode] unl
1fea0 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  ess single-threa
1feb0 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75  d was.** previou
1fec0 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20  sly selected at 
1fed0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
1fee0 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e  start-time..** ^
1fef0 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
1ff00 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c  _SHAREDCACHE] fl
1ff10 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
1ff20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ff30 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69  n to be.** eligi
1ff40 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72  ble to use [shar
1ff50 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20  ed cache mode], 
1ff60 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
1ff70 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
1ff80 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
1ff90 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73  enabled using [s
1ffa0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
1ffb0 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20  ared_cache()].  
1ffc0 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ^The.** [SQLITE_
1ffd0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
1ffe0 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
1fff0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
20000 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a  ection to not.**
20010 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20   participate in 
20020 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
20030 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69  de] even if it i
20040 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
20050 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
20060 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
20070 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
20080 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
20090 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
200a0 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
200b0 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
200c0 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
200d0 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
200e0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
200f0 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
20100 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72  e.  ^If the four
20110 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
20120 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
20130 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
20140 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
20150 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
20160 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
20170 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d  ilename is ":mem
20180 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72  ory:", then a pr
20190 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
201a0 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
201b0 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65  ase.** is create
201c0 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  d for the connec
201d0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d  tion.  ^This in-
201e0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20  memory database 
201f0 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e  will vanish when
20200 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
20210 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
20220 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76  losed.  Future v
20230 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
20240 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20  e might.** make 
20250 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61  use of additiona
20260 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61  l special filena
20270 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77  mes that begin w
20280 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72  ith the ":" char
20290 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20  acter..** It is 
202a0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
202b0 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
202c0 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c   filename actual
202d0 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69  ly does begin wi
202e0 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72  th.** a ":" char
202f0 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64  acter you should
20300 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65   prefix the file
20310 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68  name with a path
20320 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20  name such as.** 
20330 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d  "./" to avoid am
20340 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  biguity..**.** ^
20350 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
20360 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  is an empty stri
20370 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  ng, then a priva
20380 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a  te, temporary.**
20390 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73   on-disk databas
203a0 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65  e will be create
203b0 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74  d.  ^This privat
203c0 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
203d0 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  be.** automatica
203e0 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73  lly deleted as s
203f0 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62  oon as the datab
20400 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
20410 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
20420 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  [[URI filenames 
20430 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  in sqlite3_open(
20440 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65  )]] <h3>URI File
20450 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  names</h3>.**.**
20460 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61   ^If [URI filena
20470 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69  me] interpretati
20480 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61  on is enabled, a
20490 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  nd the filename 
204a0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69  argument.** begi
204b0 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c  ns with "file:",
204c0 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61   then the filena
204d0 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  me is interprete
204e0 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49  d as a URI. ^URI
204f0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  .** filename int
20500 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
20510 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53  nabled if the [S
20520 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
20530 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69  flag is.** set i
20540 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
20550 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
20560 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69  _open_v2(), or i
20570 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e  f it has.** been
20580 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c   enabled globall
20590 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  y using the [SQL
205a0 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20  ITE_CONFIG_URI] 
205b0 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a  option with the.
205c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
205d0 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20  ig()] method or 
205e0 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  by the [SQLITE_U
205f0 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d  SE_URI] compile-
20600 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
20610 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  As of SQLite ver
20620 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20  sion 3.7.7, URI 
20630 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
20640 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65  etation is turne
20650 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61  d off.** by defa
20660 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20  ult, but future 
20670 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
20680 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20  te might enable 
20690 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  URI filename.** 
206a0 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62  interpretation b
206b0 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20  y default.  See 
206c0 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d  "[URI filenames]
206d0 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  " for additional
206e0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
206f0 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  .**.** URI filen
20700 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20  ames are parsed 
20710 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43  according to RFC
20720 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55   3986. ^If the U
20730 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a  RI contains an.*
20740 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65  * authority, the
20750 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74  n it must be eit
20760 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72  her an empty str
20770 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e  ing or the strin
20780 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74  g .** "localhost
20790 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  ". ^If the autho
207a0 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65  rity is not an e
207b0 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22  mpty string or "
207c0 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a  localhost", an .
207d0 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  ** error is retu
207e0 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c  rned to the call
207f0 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e  er. ^The fragmen
20800 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
20810 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65   URI, if .** pre
20820 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64  sent, is ignored
20830 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
20840 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f  uses the path co
20850 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55  mponent of the U
20860 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f  RI as the name o
20870 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a  f the disk file.
20880 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e  ** which contain
20890 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  s the database. 
208a0 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67  ^If the path beg
208b0 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63  ins with a '/' c
208c0 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68  haracter, .** th
208d0 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72  en it is interpr
208e0 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c  eted as an absol
208f0 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68  ute path. ^If th
20900 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20  e path does not 
20910 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61  begin .** with a
20920 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68   '/' (meaning th
20930 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  at the authority
20940 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74   section is omit
20950 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49  ted from the URI
20960 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61  ).** then the pa
20970 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  th is interprete
20980 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20  d as a relative 
20990 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69  path. .** ^On wi
209a0 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74  ndows, the first
209b0 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e   component of an
209c0 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a   absolute path .
209d0 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70  ** is a drive sp
209e0 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67  ecification (e.g
209f0 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b  . "C:")..**.** [
20a00 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20  [core URI query 
20a10 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20  parameters]].** 
20a20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  The query compon
20a30 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79  ent of a URI may
20a40 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74   contain paramet
20a50 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74  ers that are int
20a60 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68  erpreted.** eith
20a70 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73  er by SQLite its
20a80 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46  elf, or by a [VF
20a90 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69  S | custom VFS i
20aa0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a  mplementation]..
20ab0 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70  ** SQLite interp
20ac0 72 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69  rets the followi
20ad0 6e 67 20 74 68 72 65 65 20 71 75 65 72 79 20 70  ng three query p
20ae0 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a  arameters:.**.**
20af0 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
20b00 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65  <b>vfs</b>: ^The
20b10 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72   "vfs" parameter
20b20 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20   may be used to 
20b30 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65  specify the name
20b40 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53   of.**     a VFS
20b50 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f   object that pro
20b60 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74  vides the operat
20b70 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
20b80 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64  face that should
20b90 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20  .**     be used 
20ba0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
20bb0 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64  tabase file on d
20bc0 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70  isk. ^If this op
20bd0 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a  tion is set to.*
20be0 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73  *     an empty s
20bf0 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c  tring the defaul
20c00 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20  t VFS object is 
20c10 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e  used. ^Specifyin
20c20 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20  g an unknown.** 
20c30 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72      VFS is an er
20c40 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  ror. ^If sqlite3
20c50 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
20c60 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f  ed and the vfs o
20c70 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
20c80 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68  present, then th
20c90 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20  e VFS specified 
20ca0 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61  by the option ta
20cb0 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f  kes precedence o
20cc0 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76  ver.**     the v
20cd0 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
20ce0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
20cf0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
20d00 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
20d10 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f    <li> <b>mode</
20d20 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70  b>: ^(The mode p
20d30 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
20d40 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72  set to either "r
20d50 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20  o", "rw",.**    
20d60 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f   "rwc", or "memo
20d70 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20  ry". Attempting 
20d80 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79  to set it to any
20d90 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a   other value is.
20da0 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29  **     an error)
20db0 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22  ^. .**     ^If "
20dc0 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64  ro" is specified
20dd0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
20de0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
20df0 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20  r read-only .** 
20e00 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74      access, just
20e10 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49   as if the [SQLI
20e20 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
20e30 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20  ] flag had been 
20e40 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20  set in the .**  
20e50 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e     third argumen
20e60 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
20e70 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20  n_v2(). ^If the 
20e80 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73  mode option is s
20e90 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72  et to .**     "r
20ea0 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  w", then the dat
20eb0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
20ec0 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28  for read-write (
20ed0 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20  but not create) 
20ee0 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
20ef0 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45  as if SQLITE_OPE
20f00 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74  N_READWRITE (but
20f10 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e   not SQLITE_OPEN
20f20 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a  _CREATE) had .**
20f30 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e       been set. ^
20f40 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65  Value "rwc" is e
20f50 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
20f60 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20  ting both .**   
20f70 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45    SQLITE_OPEN_RE
20f80 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49  ADWRITE and SQLI
20f90 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20  TE_OPEN_CREATE. 
20fa0 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
20fb0 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73  tion is.**     s
20fc0 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74  et to "memory" t
20fd0 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d  hen a pure [in-m
20fe0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20  emory database] 
20ff0 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73  that never reads
21000 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65  .**     or write
21010 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75  s from disk is u
21020 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65  sed. ^It is an e
21030 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20  rror to specify 
21040 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20  a value for.**  
21050 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61     the mode para
21060 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65  meter that is le
21070 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74  ss restrictive t
21080 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69  han that specifi
21090 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65  ed by.**     the
210a0 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e   flags passed in
210b0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
210c0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
210d0 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
210e0 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65     <li> <b>cache
210f0 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65  </b>: ^The cache
21100 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
21110 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
21120 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20  "shared" or.**  
21130 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53     "private". ^S
21140 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68  etting it to "sh
21150 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c  ared" is equival
21160 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
21170 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  he.**     SQLITE
21180 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
21190 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61  E bit in the fla
211a0 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  gs argument pass
211b0 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c  ed to.**     sql
211c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
211d0 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63  ^Setting the cac
211e0 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  he parameter to 
211f0 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a  "private" is .**
21200 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20       equivalent 
21210 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53  to setting the S
21220 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
21230 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20  TECACHE bit..** 
21240 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f      ^If sqlite3_
21250 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
21260 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65  d and the "cache
21270 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  " parameter is p
21280 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20  resent in.**    
21290 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c   a URI filename,
212a0 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72   its value overr
212b0 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f  ides any behavio
212c0 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73  r requested by s
212d0 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51  etting.**     SQ
212e0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
212f0 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45  ECACHE or SQLITE
21300 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
21310 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  E flag..** </ul>
21320 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69  .**.** ^Specifyi
21330 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61  ng an unknown pa
21340 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71  rameter in the q
21350 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
21360 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61  f a URI is not a
21370 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74  n.** error.  Fut
21380 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
21390 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64  SQLite might und
213a0 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e  erstand addition
213b0 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61  al query.** para
213c0 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71  meters.  See "[q
213d0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20  uery parameters 
213e0 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61  with special mea
213f0 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22  ning to SQLite]"
21400 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
21410 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
21420 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
21430 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20  name examples]] 
21440 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65  <h3>URI filename
21450 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a   examples</h3>.*
21460 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  *.** <table bord
21470 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e  er="1" align=cen
21480 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  ter cellpadding=
21490 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55  5>.** <tr><th> U
214a0 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68  RI filenames <th
214b0 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72  > Results.** <tr
214c0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
214d0 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
214e0 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69       Open the fi
214f0 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
21500 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
21510 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ctory..** <tr><t
21520 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
21530 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a  ed/data.db<br>.*
21540 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
21550 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ///home/fred/dat
21560 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20  a.db <br> .**   
21570 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f         file://lo
21580 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65  calhost/home/fre
21590 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c  d/data.db <br> <
215a0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
215b0 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   Open the databa
215c0 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  se file "/home/f
215d0 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a  red/data.db"..**
215e0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
215f0 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66  /darkstar/home/f
21600 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e  red/data.db <td>
21610 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
21620 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61   error. "darksta
21630 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f  r" is not a reco
21640 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79  gnized authority
21650 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79  ..** <tr><td sty
21660 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a  le="white-space:
21670 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20  nowrap"> .**    
21680 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a        file:///C:
21690 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64  /Documents%20and
216a0 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64  %20Settings/fred
216b0 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62  /Desktop/data.db
216c0 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e  .**     <td> Win
216d0 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20  dows only: Open 
216e0 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
216f0 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73  b" on fred's des
21700 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a  ktop on drive.**
21710 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f            C:. No
21720 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20  te that the %20 
21730 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73  escaping in this
21740 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20   example is not 
21750 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20  strictly .**    
21760 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20        necessary 
21770 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65  - space characte
21780 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c  rs can be used l
21790 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20  iterally.**     
217a0 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65       in URI file
217b0 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  names..** <tr><t
217c0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
217d0 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72  mode=ro&cache=pr
217e0 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20  ivate <td> .**  
217f0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
21800 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
21810 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
21820 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e  tory for read-on
21830 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20  ly access..**   
21840 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73         Regardles
21850 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
21860 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65  not shared-cache
21870 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
21880 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   by.**          
21890 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70  default, use a p
218a0 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a  rivate cache..**
218b0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
218c0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
218d0 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63  b?vfs=unix-noloc
218e0 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20  k <td>.**       
218f0 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68     Open file "/h
21900 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
21910 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69  ". Use the speci
21920 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c  al VFS "unix-nol
21930 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ock"..** <tr><td
21940 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
21950 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64  ode=readonly <td
21960 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
21970 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e  n error. "readon
21980 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c  ly" is not a val
21990 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68  id option for th
219a0 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74  e "mode" paramet
219b0 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  er..** </table>.
219c0 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64  **.** ^URI hexad
219d0 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
219e0 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72  quences (%HH) ar
219f0 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68  e supported with
21a00 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a  in the path and.
21a10 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  ** query compone
21a20 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20  nts of a URI. A 
21a30 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
21a40 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73  pe sequence cons
21a50 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72  ists of a.** per
21a60 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20  cent sign - "%" 
21a70 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78  - followed by ex
21a80 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65  actly two hexade
21a90 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a  cimal digits .**
21aa0 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f   specifying an o
21ab0 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66  ctet value. ^Bef
21ac0 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20  ore the path or 
21ad0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
21ae0 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c   of a.** URI fil
21af0 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70  ename are interp
21b00 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20  reted, they are 
21b10 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
21b20 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20  F-8 and all .** 
21b30 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
21b40 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70  pe sequences rep
21b50 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c  laced by a singl
21b60 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e  e byte containin
21b70 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70  g the.** corresp
21b80 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66  onding octet. If
21b90 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65   this process ge
21ba0 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c  nerates an inval
21bb0 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  id UTF-8 encodin
21bc0 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  g,.** the result
21bd0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
21be0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
21bf0 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
21c00 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
21c10 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
21c20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
21c30 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
21c40 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
21c50 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
21c60 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
21c70 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
21c80 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
21c90 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
21ca0 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
21cb0 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
21cc0 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
21cd0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
21ce0 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
21cf0 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
21d00 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
21d10 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
21d20 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
21d30 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
21d40 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
21d50 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
21d60 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
21d70 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
21d80 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
21d90 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
21da0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
21db0 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  2().  Otherwise,
21dc0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
21dd0 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
21de0 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
21df0 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
21e00 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   fail..**.** See
21e10 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
21e20 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a  temp_directory].
21e30 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
21e40 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
21e50 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
21e60 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
21e70 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
21e80 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
21e90 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
21ea0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
21eb0 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
21ec0 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
21ed0 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
21ee0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
21ef0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
21f00 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
21f10 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
21f20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
21f30 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
21f40 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
21f50 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
21f60 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
21f70 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
21f80 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
21f90 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
21fa0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
21fb0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
21fc0 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
21fd0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
21fe0 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
21ff0 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
22000 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
22010 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
22020 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
22030 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
22040 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50  Values For URI P
22050 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
22060 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74  These are utilit
22070 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66  y routines, usef
22080 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d  ul to VFS implem
22090 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20  entations, that 
220a0 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20  check.** to see 
220b0 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69  if a database fi
220c0 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61  le was a URI tha
220d0 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70  t contained a sp
220e0 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a  ecific query .**
220f0 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20   parameter, and 
22100 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68  if so obtains th
22110 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
22120 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e  query parameter.
22130 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74  .**.** If F is t
22140 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
22150 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73  name pointer pas
22160 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
22170 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a  en() method of .
22180 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65  ** a VFS impleme
22190 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65  ntation when the
221a0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
221b0 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20   to xOpen() has 
221c0 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20  one or .** more 
221d0 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  of the [SQLITE_O
221e0 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c  PEN_URI] or [SQL
221f0 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
22200 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a  ] bits set and.*
22210 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20  * P is the name 
22220 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72  of the query par
22230 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  ameter, then.** 
22240 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
22250 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
22260 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
22270 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74  the P.** paramet
22280 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20  er if it exists 
22290 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
222a0 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20  r if P does not 
222b0 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20  appear as a .** 
222c0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
222d0 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61  on F.  If P is a
222e0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
222f0 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20   of F.** has no 
22300 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20  explicit value, 
22310 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
22320 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
22330 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69  returns.** a poi
22340 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79  nter to an empty
22350 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
22360 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
22370 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
22380 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68  utine assumes th
22390 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61  at P is a boolea
223a0 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61  n.** parameter a
223b0 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  nd returns true 
223c0 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29  (1) or false (0)
223d0 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68   according to th
223e0 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e  e value.** of P.
223f0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72    The sqlite3_ur
22400 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
22410 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
22420 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65   true (1) if the
22430 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65  .** value of que
22440 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
22450 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20  s one of "yes", 
22460 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20  "true", or "on" 
22470 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f  in any.** case o
22480 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  r if the value b
22490 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e  egins with a non
224a0 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54  -zero number.  T
224b0 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  he .** sqlite3_u
224c0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
224d0 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  ) routines retur
224e0 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20  ns false (0) if 
224f0 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  the value of.** 
22500 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
22510 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22  P is one of "no"
22520 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f  , "false", or "o
22530 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20  ff" in any case 
22540 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c  or.** if the val
22550 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
22560 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20   numeric zero.  
22570 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75  If P is not a qu
22580 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
22590 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20   on F or if the 
225a0 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f  value of P is do
225b0 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79  es not match any
225c0 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65   of the.** above
225d0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
225e0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
225f0 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29  ) returns (B!=0)
22600 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
22610 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c  te3_uri_int64(F,
22620 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e  P,D) routine con
22630 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20  verts the value 
22640 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36  of P into a.** 6
22650 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
22660 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eger and returns
22670 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f   that integer, o
22680 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  r D if P does no
22690 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20  t.** exist.  If 
226a0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
226b0 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  s something othe
226c0 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65  r than an intege
226d0 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20  r, then.** zero 
226e0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
226f0 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55  .** If F is a NU
22700 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
22710 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
22720 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
22730 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20  rns NULL and.** 
22740 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
22750 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
22760 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e  ns B.  If F is n
22770 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ot a NULL pointe
22780 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20  r and.** is not 
22790 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
227a0 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72  pathname pointer
227b0 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73   that SQLite pas
227c0 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
227d0 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64  en.** VFS method
227e0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
227f0 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ior of this rout
22800 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ine is undefined
22810 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a   and probably.**
22820 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
22830 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
22840 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
22850 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  er(const char *z
22860 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20  Filename, const 
22870 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69  char *zParam);.i
22880 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  nt sqlite3_uri_b
22890 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61  oolean(const cha
228a0 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20  r *zFile, const 
228b0 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e  char *zParam, in
228c0 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c  t bDefault);.sql
228d0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
228e0 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e  e3_uri_int64(con
228f0 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20  st char*, const 
22900 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  char*, sqlite3_i
22910 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt64);.../*.** C
22920 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
22930 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
22940 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
22950 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
22960 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
22970 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65   the numeric [re
22980 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  sult code] or.**
22990 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
229a0 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  t code] for the 
229b0 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c  most recent fail
229c0 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  ed sqlite3_* API
229d0 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61   call.** associa
229e0 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61  ted with a [data
229f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
22a00 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49  . If a prior API
22a10 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20   call failed.** 
22a20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  but the most rec
22a30 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63  ent API call suc
22a40 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75  ceeded, the retu
22a50 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a  rn value from.**
22a60 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
22a70 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
22a80 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65    ^The sqlite3_e
22a90 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
22aa0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
22ab0 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70  s the same excep
22ac0 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73  t that it always
22ad0 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a   returns the .**
22ae0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
22af0 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65  t code] even whe
22b00 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  n extended resul
22b10 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64  t codes are.** d
22b20 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
22b30 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  The sqlite3_errm
22b40 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  sg() and sqlite3
22b50 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75  _errmsg16() retu
22b60 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
22b70 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74  age.** text that
22b80 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
22b90 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20  rror, as either 
22ba0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
22bb0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
22bc0 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
22bd0 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
22be0 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
22bf0 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
22c00 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
22c10 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
22c20 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75  ed to worry abou
22c30 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65  t freeing the re
22c40 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  sult..** However
22c50 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  , the error stri
22c60 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72  ng might be over
22c70 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
22c80 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62  ocated by.** sub
22c90 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
22ca0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
22cb0 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
22cc0 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s.)^.**.** ^The 
22cd0 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29  sqlite3_errstr()
22ce0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
22cf0 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c  ns the English-l
22d00 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20  anguage text.** 
22d10 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
22d20 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  he [result code]
22d30 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e  , as UTF-8..** ^
22d40 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
22d50 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
22d60 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
22d70 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a  ged internally.*
22d80 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62  * and must not b
22d90 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61  e freed by the a
22da0 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a  pplication)^..**
22db0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
22dc0 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
22dd0 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
22de0 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
22df0 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
22e00 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
22e10 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
22e20 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
22e30 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
22e40 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
22e50 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
22e60 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
22e70 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
22e80 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
22e90 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
22ea0 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
22eb0 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
22ec0 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
22ed0 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
22ee0 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
22ef0 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
22f00 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
22f10 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
22f20 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
22f30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22f40 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
22f50 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
22f60 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
22f70 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
22f80 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
22f90 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
22fa0 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
22fb0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
22fc0 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
22fd0 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
22fe0 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
22ff0 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
23000 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
23010 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
23020 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
23030 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
23040 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
23050 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
23060 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
23070 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
23080 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
23090 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
230a0 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
230b0 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
230c0 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
230d0 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c   set..*/.int sql
230e0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
230f0 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73  ite3 *db);.int s
23100 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
23110 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
23120 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  *db);.const char
23130 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
23140 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
23150 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
23160 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
23170 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  *);.const char *
23180 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69  sqlite3_errstr(i
23190 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
231a0 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d  3REF: SQL Statem
231b0 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  ent Object.** KE
231c0 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65  YWORDS: {prepare
231d0 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72  d statement} {pr
231e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
231f0 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  s}.**.** An inst
23200 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
23210 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
23220 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
23230 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  ement..** This o
23240 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73  bject is various
23250 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70  ly known as a "p
23260 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23270 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70  t" or a.** "comp
23280 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  iled SQL stateme
23290 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73  nt" or simply as
232a0 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a   a "statement"..
232b0 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f  **.** The life o
232c0 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  f a statement ob
232d0 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68  ject goes someth
232e0 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ing like this:.*
232f0 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
23300 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a  > Create the obj
23310 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
23320 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
23330 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a   or a related.**
23340 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a        function..
23350 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c  ** <li> Bind val
23360 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72  ues to [host par
23370 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74  ameters] using t
23380 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
23390 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65  *().**      inte
233a0 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20  rfaces..** <li> 
233b0 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63  Run the SQL by c
233c0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
233d0 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d  step()] one or m
233e0 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
233f0 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61  i> Reset the sta
23400 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
23410 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
23420 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20  hen go back.**  
23430 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20      to step 2.  
23440 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20  Do this zero or 
23450 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
23460 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20  li> Destroy the 
23470 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
23480 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
23490 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a  ]..** </ol>.**.*
234a0 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d  * Refer to docum
234b0 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69  entation on indi
234c0 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61  vidual methods a
234d0 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f  bove for additio
234e0 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
234f0 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  on..*/.typedef s
23500 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74  truct sqlite3_st
23510 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b  mt sqlite3_stmt;
23520 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23530 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74  : Run-time Limit
23540 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69  s.**.** ^(This i
23550 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20  nterface allows 
23560 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69  the size of vari
23570 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74  ous constructs t
23580 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20  o be limited.** 
23590 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  on a connection 
235a0 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  by connection ba
235b0 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20  sis.  The first 
235c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
235d0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
235e0 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20  nnection] whose 
235f0 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73  limit is to be s
23600 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20  et or queried.  
23610 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
23620 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f  rameter is one o
23630 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74  f the [limit cat
23640 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65  egories] that de
23650 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20  fine a.** class 
23660 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  of constructs to
23670 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64   be size limited
23680 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72  .  The third par
23690 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
236a0 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74   new limit for t
236b0 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e  hat construct.)^
236c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
236d0 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65  ew limit is a ne
236e0 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74  gative number, t
236f0 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68  he limit is unch
23700 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20  anged..** ^(For 
23710 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67  each limit categ
23720 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ory SQLITE_LIMIT
23730 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65  _<i>NAME</i> the
23740 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d  re is a .** [lim
23750 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72  its | hard upper
23760 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61   bound].** set a
23770 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62  t compile-time b
23780 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73  y a C preprocess
23790 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a  or macro called.
237a0 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c  ** [limits | SQL
237b0 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c  ITE_MAX_<i>NAME<
237c0 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f  /i>]..** (The "_
237d0 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e  LIMIT_" in the n
237e0 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74  ame is changed t
237f0 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a  o "_MAX_".))^.**
23800 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e   ^Attempts to in
23810 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61  crease a limit a
23820 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70  bove its hard up
23830 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a  per bound are.**
23840 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
23850 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20  ted to the hard 
23860 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a  upper bound..**.
23870 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f  ** ^Regardless o
23880 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
23890 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63   the limit was c
238a0 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20  hanged, the .** 
238b0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
238c0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
238d0 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61  rns the prior va
238e0 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74  lue of the limit
238f0 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20  ..** ^Hence, to 
23900 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74  find the current
23910 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69   value of a limi
23920 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69  t without changi
23930 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79  ng it,.** simply
23940 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74   invoke this int
23950 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20  erface with the 
23960 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
23970 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a  set to -1..**.**
23980 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73   Run-time limits
23990 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
239a0 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61  r use in applica
239b0 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67  tions that manag
239c0 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20  e.** both their 
239d0 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  own internal dat
239e0 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64  abase and also d
239f0 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72  atabases that ar
23a00 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20  e controlled.** 
23a10 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74  by untrusted ext
23a20 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20  ernal sources.  
23a30 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69  An example appli
23a40 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  cation might be 
23a50 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72  a.** web browser
23a60 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77   that has its ow
23a70 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20  n databases for 
23a80 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20  storing history 
23a90 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20  and.** separate 
23aa0 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f  databases contro
23ab0 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69  lled by JavaScri
23ac0 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  pt applications 
23ad0 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66  downloaded.** of
23ae0 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20  f the Internet. 
23af0 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61   The internal da
23b00 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67  tabases can be g
23b10 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67  iven the.** larg
23b20 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74  e, default limit
23b30 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61  s.  Databases ma
23b40 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61  naged by externa
23b50 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a  l sources can.**
23b60 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73   be given much s
23b70 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65  maller limits de
23b80 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e  signed to preven
23b90 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65  t a denial of se
23ba0 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e  rvice.** attack.
23bb0 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67    Developers mig
23bc0 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20  ht also want to 
23bd0 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
23be0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
23bf0 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
23c00 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72  to further contr
23c10 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c  ol untrusted SQL
23c20 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
23c30 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
23c40 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74  reated by an unt
23c50 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61  rusted script ca
23c60 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75  n be contained u
23c70 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78  sing the.** [max
23c80 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
23c90 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  AGMA]..**.** New
23ca0 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20   run-time limit 
23cb0 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62  categories may b
23cc0 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
23cd0 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69  e releases..*/.i
23ce0 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  nt sqlite3_limit
23cf0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
23d00 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
23d10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23d20 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
23d30 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45  Categories.** KE
23d40 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
23d50 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74  ategory} {*limit
23d60 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
23d70 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
23d80 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
23d90 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
23da0 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
23db0 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
23dc0 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
23dd0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
23de0 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
23df0 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
23e00 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
23e10 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
23e20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
23e30 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
23e40 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
23e50 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
23e60 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
23e70 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
23e80 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
23e90 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
23ea0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
23eb0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
23ec0 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
23ed0 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
23ee0 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
23ef0 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
23f00 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
23f10 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d  MIT_SQL_LENGTH]]
23f20 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
23f30 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
23f40 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
23f50 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
23f60 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
23f70 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  t, in bytes.</dd
23f80 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
23f90 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d  TE_LIMIT_COLUMN]
23fa0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
23fb0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
23fc0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
23fd0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
23fe0 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
23ff0 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
24000 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
24010 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
24020 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  ] or the maximum
24030 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
24040 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
24050 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
24060 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
24070 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  clause.</dd>)^.*
24080 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
24090 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d  MIT_EXPR_DEPTH]]
240a0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
240b0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
240c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
240d0 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
240e0 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
240f0 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
24100 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
24110 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
24120 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20  MPOUND_SELECT]] 
24130 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
24140 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
24150 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
24160 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
24170 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
24180 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
24190 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29  statement.</dd>)
241a0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
241b0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d  _LIMIT_VDBE_OP]]
241c0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
241d0 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
241e0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
241f0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
24200 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
24210 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
24220 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
24230 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
24240 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
24250 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f  This limit is no
24260 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65  t currently.** e
24270 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20  nforced, though 
24280 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64  that might be ad
24290 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ded in some futu
242a0 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
242b0 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a   SQLite.</dd>)^.
242c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
242d0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
242e0 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  G]] ^(<dt>SQLITE
242f0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
24300 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
24310 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
24320 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
24330 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
24340 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
24350 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
24360 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  HED]] ^(<dt>SQLI
24370 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
24380 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
24390 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
243a0 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
243b0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
243c0 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
243d0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
243e0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
243f0 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  TH]].** ^(<dt>SQ
24400 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
24410 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
24420 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
24430 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
24440 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
24450 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49  ument to the [LI
24460 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d  KE] or.** [GLOB]
24470 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e   operators.</dd>
24480 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
24490 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
244a0 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c  _NUMBER]].** ^(<
244b0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
244c0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
244d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
244e0 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75  maximum index nu
244f0 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72  mber of any [par
24500 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51  ameter] in an SQ
24510 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a  L statement.)^.*
24520 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
24530 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
24540 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
24550 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
24560 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
24570 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
24580 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20  th of recursion 
24590 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64  for triggers.</d
245a0 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  d>)^.** </dl>.*/
245b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
245c0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20  LIMIT_LENGTH    
245d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
245e0 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
245f0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
24600 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
24610 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
24620 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20  E_LIMIT_COLUMN  
24630 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24640 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
24650 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
24660 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  PTH             
24670 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
24680 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
24690 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  ND_SELECT       
246a0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
246b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
246c0 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  OP              
246d0 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
246e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
246f0 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20  TION_ARG        
24700 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
24710 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
24720 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20  ACHED           
24730 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
24740 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49   SQLITE_LIMIT_LI
24750 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
24760 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e  H       8.#defin
24770 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
24780 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20  ARIABLE_NUMBER  
24790 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
247a0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
247b0 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20  TRIGGER_DEPTH   
247c0 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a           10../*.
247d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
247e0 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
247f0 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f  atement.** KEYWO
24800 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d  RDS: {SQL statem
24810 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a  ent compiler}.**
24820 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61  .** To execute a
24830 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20  n SQL query, it 
24840 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f  must first be co
24850 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79  mpiled into a by
24860 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72  te-code.** progr
24870 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  am using one of 
24880 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
24890 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
248a0 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20  argument, "db", 
248b0 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
248c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69  onnection] obtai
248d0 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72  ned from a.** pr
248e0 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
248f0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
24900 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
24910 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a  3_open_v2()] or.
24920 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
24930 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61  16()].  The data
24940 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
24950 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65  must not have be
24960 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  en closed..**.**
24970 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
24980 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73  ment, "zSql", is
24990 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
249a0 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
249b0 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
249c0 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
249d0 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
249e0 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
249f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
24a00 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v2().** interfac
24a10 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e  es use UTF-8, an
24a20 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
24a30 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65  e16() and sqlite
24a40 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
24a50 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a  .** use UTF-16..
24a60 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42  **.** ^If the nB
24a70 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  yte argument is 
24a80 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20  less than zero, 
24a90 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61  then zSql is rea
24aa0 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66  d up to the.** f
24ab0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
24ac0 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20  ator. ^If nByte 
24ad0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
24ae0 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20   then it is the 
24af0 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65  maximum.** numbe
24b00 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64  r of  bytes read
24b10 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68   from zSql.  ^Wh
24b20 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  en nByte is non-
24b30 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a  negative, the.**
24b40 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64   zSql string end
24b50 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20  s at either the 
24b60 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20  first '\000' or 
24b70 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74  '\u0000' charact
24b80 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79  er or.** the nBy
24b90 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63  te-th byte, whic
24ba0 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
24bb0 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72  t. If the caller
24bc0 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74   knows.** that t
24bd0 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
24be0 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
24bf0 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65  ated, then there
24c00 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70   is a small.** p
24c10 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
24c20 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65  tage to be gaine
24c30 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20  d by passing an 
24c40 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20  nByte parameter 
24c50 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c  that.** is equal
24c60 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   to the number o
24c70 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69  f bytes in the i
24c80 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69  nput string <i>i
24c90 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20  ncluding</i>.** 
24ca0 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  the nul-terminat
24cb0 6f 72 20 62 79 74 65 73 20 61 73 20 74 68 69 73  or bytes as this
24cc0 20 73 61 76 65 73 20 53 51 4c 69 74 65 20 66 72   saves SQLite fr
24cd0 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a 20  om having to.** 
24ce0 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74  make a copy of t
24cf0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
24d00 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69  .**.** ^If pzTai
24d10 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  l is not NULL th
24d20 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  en *pzTail is ma
24d30 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
24d40 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a  he first byte.**
24d50 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
24d60 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
24d70 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
24d80 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
24d90 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c  s only.** compil
24da0 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74  e the first stat
24db0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73  ement in zSql, s
24dc0 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66  o *pzTail is lef
24dd0 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a  t pointing to.**
24de0 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e   what remains un
24df0 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
24e00 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74  ^*ppStmt is left
24e10 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
24e20 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
24e30 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
24e40 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
24e50 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
24e60 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49  te3_step()].  ^I
24e70 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
24e80 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20  ror, *ppStmt is 
24e90 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20  set.** to NULL. 
24ea0 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74   ^If the input t
24eb0 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  ext contains no 
24ec0 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75  SQL (if the inpu
24ed0 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a  t is an empty.**
24ee0 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d   string or a com
24ef0 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74  ment) then *ppSt
24f00 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c  mt is set to NUL
24f10 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e  L..** The callin
24f20 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
24f30 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
24f40 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
24f50 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
24f60 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
24f70 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
24f80 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
24f90 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
24fa0 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f  ** ppStmt may no
24fb0 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  t be NULL..**.**
24fc0 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68   ^On success, th
24fd0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
24fe0 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f  e() family of ro
24ff0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
25000 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74  QLITE_OK];.** ot
25010 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
25020 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
25030 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
25040 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
25050 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  2() and sqlite3_
25060 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69  prepare16_v2() i
25070 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a  nterfaces are.**
25080 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
25090 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
250a0 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72  s. The two older
250b0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
250c0 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20  retained.** for 
250d0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
250e0 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
250f0 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
25100 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68  raged..** ^In th
25110 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
25120 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20  s, the prepared 
25130 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61  statement.** tha
25140 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74  t is returned (t
25150 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
25160 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69  ] object) contai
25170 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
25180 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
25190 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73   text. This caus
251a0 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  es the [sqlite3_
251b0 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63  step()] interfac
251c0 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64  e to.** behave d
251d0 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68  ifferently in th
251e0 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ree ways:.**.** 
251f0 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  <ol>.** <li>.** 
25200 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  ^If the database
25210 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
25220 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
25230 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
25240 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
25250 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
25260 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
25270 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
25280 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
25290 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
252a0 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
252b0 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a 2a  run it again..**
252c0 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
252d0 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72  >.** ^When an er
252e0 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c  ror occurs, [sql
252f0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
25300 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
25310 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20  the detailed.** 
25320 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72  [error codes] or
25330 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
25340 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c   codes].  ^The l
25350 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77  egacy behavior w
25360 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69  as that.** [sqli
25370 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c  te3_step()] woul
25380 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20  d only return a 
25390 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f  generic [SQLITE_
253a0 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f  ERROR] result co
253b0 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70  de.** and the ap
253c0 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20  plication would 
253d0 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
253e0 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73  econd call to [s
253f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a  qlite3_reset()].
25400 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  ** in order to f
25410 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
25420 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
25430 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68  problem. With th
25440 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a  e "v2" prepare.*
25450 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  * interfaces, th
25460 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61  e underlying rea
25470 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f  son for the erro
25480 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  r is returned im
25490 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
254a0 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
254b0 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
254c0 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74  ic value bound t
254d0 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68  o [parameter | h
254e0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69  ost parameter] i
254f0 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20  n the .** WHERE 
25500 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66  clause might inf
25510 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63  luence the choic
25520 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
25530 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  for a statement,
25540 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61  .** then the sta
25550 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61  tement will be a
25560 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
25570 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74  ompiled, as if t
25580 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a  here had been .*
25590 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  * a schema chang
255a0 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20  e, on the first 
255b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
255c0 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67  ] call following
255d0 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74   any change.** t
255e0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  o the [sqlite3_b
255f0 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69  ind_text | bindi
25600 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61  ngs] of that [pa
25610 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54  rameter]. .** ^T
25620 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
25630 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73  e of WHERE-claus
25640 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69  e [parameter] mi
25650 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
25660 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20  e .** choice of 
25670 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68  query plan if th
25680 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  e parameter is t
25690 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64  he left-hand sid
256a0 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a  e of a [LIKE].**
256b0 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61   or [GLOB] opera
256c0 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61  tor or if the pa
256d0 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61  rameter is compa
256e0 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65  red to an indexe
256f0 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20  d column.** and 
25700 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  the [SQLITE_ENAB
25710 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c  LE_STAT3] compil
25720 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
25730 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65   enabled..** the
25740 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f   .** </li>.** </
25750 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ol>.*/.int sqlit
25760 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
25770 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
25780 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
25790 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
257a0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
257b0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
257c0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
257d0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
257e0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
257f0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
25800 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
25810 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
25820 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
25830 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
25840 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
25850 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
25860 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
25870 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
25880 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
25890 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
258a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
258b0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
258c0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
258d0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
258e0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
258f0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
25900 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
25910 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
25920 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
25930 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
25940 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
25950 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
25960 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
25970 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
25980 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
25990 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
259a0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
259b0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
259c0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
259d0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
259e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
259f0 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
25a00 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
25a10 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
25a20 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
25a30 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
25a40 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
25a50 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
25a60 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
25a70 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
25a80 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
25a90 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
25aa0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
25ab0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
25ac0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
25ad0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
25ae0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
25af0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
25b00 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
25b10 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
25b20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
25b30 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
25b40 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
25b50 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
25b60 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
25b70 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
25b80 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
25b90 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
25ba0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
25bb0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
25bc0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
25bd0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
25be0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
25bf0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
25c00 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
25c10 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
25c20 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
25c30 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
25c40 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
25c50 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
25c60 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
25c70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25c80 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
25c90 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e  ment SQL.**.** ^
25ca0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
25cb0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
25cc0 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63  trieve a saved c
25cd0 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69  opy of the origi
25ce0 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  nal.** SQL text 
25cf0 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61  used to create a
25d00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25d10 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74  ment] if that st
25d20 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63  atement was.** c
25d30 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
25d40 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
25d50 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
25d60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
25d70 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  6_v2()]..*/.cons
25d80 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
25d90 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
25da0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
25db0 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
25dc0 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
25dd0 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20  tatement Writes 
25de0 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a  The Database.**.
25df0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
25e00 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29  stmt_readonly(X)
25e10 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
25e20 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
25e30 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  o) if.** and onl
25e40 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72  y if the [prepar
25e50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20  ed statement] X 
25e60 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20  makes no direct 
25e70 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68  changes to.** th
25e80 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
25e90 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
25ea0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
25eb0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
25ec0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
25ed0 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75  ns] or.** [virtu
25ee0 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74  al tables] might
25ef0 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
25f00 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20  base indirectly 
25f10 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74  as a side effect
25f20 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .  .** ^(For exa
25f30 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c  mple, if an appl
25f40 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20  ication defines 
25f50 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c  a function "eval
25f60 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c  ()" that .** cal
25f70 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ls [sqlite3_exec
25f80 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  ()], then the fo
25f90 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74  llowing SQL stat
25fa0 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63  ement would.** c
25fb0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
25fc0 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20  se file through 
25fd0 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a  side-effects:.**
25fe0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
25ff0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45  <pre>.**    SELE
26000 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20  CT eval('DELETE 
26010 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74  FROM t1') FROM t
26020 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  2;.** </pre></bl
26030 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
26040 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20  But because the 
26050 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
26060 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nt does not chan
26070 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
26080 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79  file.** directly
26090 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  , sqlite3_stmt_r
260a0 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20  eadonly() would 
260b0 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75  still return tru
260c0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e  e.)^.**.** ^Tran
260d0 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20  saction control 
260e0 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20  statements such 
260f0 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d  as [BEGIN], [COM
26100 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d  MIT], [ROLLBACK]
26110 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d  ,.** [SAVEPOINT]
26120 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20  , and [RELEASE] 
26130 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74  cause sqlite3_st
26140 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
26150 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a   return true,.**
26160 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65   since the state
26170 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73  ments themselves
26180 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79   do not actually
26190 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
261a0 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68  base but.** rath
261b0 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20  er they control 
261c0 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68  the timing of wh
261d0 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65  en other stateme
261e0 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a  nts modify the .
261f0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54  ** database.  ^T
26200 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20  he [ATTACH] and 
26210 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65  [DETACH] stateme
26220 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a  nts also cause.*
26230 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
26240 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
26250 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20  urn true since, 
26260 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74  while those stat
26270 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65  ements.** change
26280 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
26290 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  on of a database
262a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65   connection, the
262b0 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a  y do not make .*
262c0 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  * changes to the
262d0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
262e0 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f  database files o
262f0 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73  n disk..*/.int s
26300 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
26310 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  only(sqlite3_stm
26320 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
26330 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
26340 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61  rmine If A Prepa
26350 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61  red Statement Ha
26360 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a  s Been Reset.**.
26370 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
26380 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74  stmt_busy(S) int
26390 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
263a0 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
263b0 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  f the.** [prepar
263c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
263d0 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64  has been stepped
263e0 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75   at least once u
263f0 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
26400 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68  3_step(S)] but h
26410 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f  as not run to co
26420 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20  mpletion and/or 
26430 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e  has not .** been
26440 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71   reset using [sq
26450 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e  lite3_reset(S)].
26460 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
26470 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69  tmt_busy(S).** i
26480 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
26490 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61   false if S is a
264a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
264b0 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a  If S is not a .*
264c0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  * NULL pointer a
264d0 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e  nd is not a poin
264e0 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b  ter to a valid [
264f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26500 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74  nt].** object, t
26510 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
26520 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
26530 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
26540 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  irable..**.** Th
26550 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
26560 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62   be used in comb
26570 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33  ination [sqlite3
26580 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a  _next_stmt()].**
26590 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70   to locate all p
265a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
265b0 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ts associated wi
265c0 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a  th a database .*
265d0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  * connection tha
265e0 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66  t are in need of
265f0 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54   being reset.  T
26600 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c  his can be used,
26610 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  .** for example,
26620 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72   in diagnostic r
26630 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63  outines to searc
26640 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a  h for prepared .
26650 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  ** statements th
26660 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61  at are holding a
26670 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65   transaction ope
26680 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
26690 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69  3_stmt_busy(sqli
266a0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
266b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
266c0 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
266d0 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  alue Object.** K
266e0 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
266f0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
26700 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
26710 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
26720 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
26730 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
26740 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
26750 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
26760 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
26770 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
26780 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
26790 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
267a0 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
267b0 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
267c0 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74  res.  ^Values st
267d0 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
267e0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
267f0 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
26800 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
26810 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
26820 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
26830 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
26840 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
26850 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
26860 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
26870 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
26880 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
26890 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
268a0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
268b0 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
268c0 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
268d0 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
268e0 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
268f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
26900 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
26910 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
26920 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
26930 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
26940 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
26950 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
26960 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
26970 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
26980 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
26990 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
269a0 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
269b0 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
269c0 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
269d0 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20  ex is held.  An 
269e0 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
269f0 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
26a00 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
26a10 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
26a20 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
26a30 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
26a40 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
26a50 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
26a60 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
26a70 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
26a80 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
26a90 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
26aa0 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
26ab0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
26ac0 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
26ad0 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
26ae0 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
26af0 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
26b00 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
26b10 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
26b20 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
26b30 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
26b40 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
26b50 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
26b60 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
26b70 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
26b80 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
26b90 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
26ba0 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
26bb0 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
26bc0 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
26bd0 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
26be0 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
26bf0 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
26c00 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
26c10 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
26c20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
26c30 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
26c40 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
26c50 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
26c60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
26c70 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
26c80 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
26c90 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
26ca0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
26cb0 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
26cc0 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
26cd0 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
26ce0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
26cf0 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
26d00 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
26d10 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
26d20 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
26d30 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
26d40 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
26d50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
26d60 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
26d70 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
26d80 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
26d90 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
26da0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
26db0 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
26dc0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
26dd0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
26de0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
26df0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
26e00 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
26e10 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
26e20 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
26e30 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
26e40 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
26e50 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
26e60 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
26e70 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
26e80 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
26e90 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
26ea0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
26eb0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
26ec0 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
26ed0 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
26ee0 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
26ef0 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
26f00 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
26f10 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
26f20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
26f30 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
26f40 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
26f50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
26f60 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
26f70 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
26f80 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
26f90 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
26fa0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
26fb0 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
26fc0 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
26fd0 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
26fe0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
26ff0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
27000 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
27010 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
27020 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
27030 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
27040 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
27050 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
27060 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
27070 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
27080 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
27090 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
270a0 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
270b0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
270c0 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
270d0 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
270e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
270f0 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
27100 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
27110 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
27120 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
27130 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
27140 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
27150 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
27160 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
27170 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
27180 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
27190 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a  r binding}.**.**
271a0 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74   ^(In the SQL st
271b0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70  atement text inp
271c0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
271d0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
271e0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
271f0 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
27200 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
27210 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74  [parameter] that
27220 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20   matches one of 
27230 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d  following.** tem
27240 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  plates:.**.** <u
27250 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
27260 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
27270 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
27280 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
27290 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
272a0 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70  *.** In the temp
272b0 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e  lates above, NNN
272c0 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69   represents an i
272d0 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
272e0 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65  ** and VVV repre
272f0 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75  sents an alphanu
27300 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72  meric identifier
27310 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  .)^  ^The values
27320 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72   of these.** par
27330 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
27340 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
27350 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22  eter names" or "
27360 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29  SQL parameters")
27370 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75  .** can be set u
27380 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
27390 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
273a0 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  es defined here.
273b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
273c0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
273d0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
273e0 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61  () routines is a
273f0 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  lways.** a point
27400 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
27410 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20  e3_stmt] object 
27420 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a  returned from.**
27430 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
27440 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
27450 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ariants..**.** ^
27460 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
27470 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
27480 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
27490 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
274a0 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  .** ^The leftmos
274b0 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
274c0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
274d0 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61  1.  ^When the sa
274e0 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20  me named.** SQL 
274f0 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
27500 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
27510 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
27520 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
27530 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
27540 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
27550 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
27560 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65  ce..** ^The inde
27570 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
27580 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
27590 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
275a0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
275b0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
275c0 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
275d0 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65  ired.  ^The inde
275e0 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
275f0 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
27600 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
27610 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75  ** ^The NNN valu
27620 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
27630 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c  n 1 and the [sql
27640 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
27650 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49   parameter [SQLI
27660 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
27670 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75  E_NUMBER] (defau
27680 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
27690 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
276a0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
276b0 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
276c0 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
276d0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73  .**.** ^(In thos
276e0 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  e routines that 
276f0 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
27700 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
27710 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
27720 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
27730 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
27740 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
27750 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
27760 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74  number of <u>byt
27770 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61  es</u> in the va
27780 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  lue, not the num
27790 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
277a0 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.)^.** ^If the 
277b0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
277c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
277d0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
277e0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
277f0 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
27800 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68   then the length
27810 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   of the string i
27820 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
27830 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74  of bytes up to t
27840 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
27850 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20  rminator..** If 
27860 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
27870 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
27880 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e  bind_blob() is n
27890 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a  egative, then.**
278a0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
278b0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
278c0 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  f a non-negative
278d0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
278e0 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f  r is provided to
278f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
27900 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  xt().** or sqlit
27910 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
27920 20 74 68 65 6e 20 74 68 61 74 20 70 61 72 61 6d   then that param
27930 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65  eter must be the
27940 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20   byte offset.** 
27950 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65  where the NUL te
27960 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f  rminator would o
27970 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68  ccur assuming th
27980 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55  e string were NU
27990 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e  L.** terminated.
279a0 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61    If any NUL cha
279b0 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74  racters occur at
279c0 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65   byte offsets le
279d0 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20  ss than .** the 
279e0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75  value of the fou
279f0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68  rth parameter th
27a00 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  en the resulting
27a10 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69   string value wi
27a20 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d  ll.** contain em
27a30 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68  bedded NULs.  Th
27a40 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72  e result of expr
27a50 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e  essions involvin
27a60 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74  g strings.** wit
27a70 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  h embedded NULs 
27a80 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
27a90 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
27aa0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
27ab0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20  e3_bind_blob(), 
27ac0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
27ad0 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  t(), and.** sqli
27ae0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
27af0 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  ) is a destructo
27b00 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
27b10 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
27b20 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
27b30 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
27b40 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e  shed with it.  ^
27b50 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
27b60 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64  s called.** to d
27b70 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
27b80 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65  OB or string eve
27b90 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  n if the call to
27ba0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
27bb0 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  ob(),.** sqlite3
27bc0 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72  _bind_text(), or
27bd0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
27be0 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a  xt16() fails.  .
27bf0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
27c00 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
27c10 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  the special valu
27c20 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  e [SQLITE_STATIC
27c30 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61  ], then SQLite a
27c40 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
27c50 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
27c60 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d  s in static, unm
27c70 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64  anaged space and
27c80 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
27c90 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  o be freed..** ^
27ca0 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
27cb0 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61  ument has the va
27cc0 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  lue [SQLITE_TRAN
27cd0 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20  SIENT], then.** 
27ce0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73  SQLite makes its
27cf0 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
27d00 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d  y of the data im
27d10 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72  mediately, befor
27d20 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  e.** the sqlite3
27d30 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
27d40 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  e returns..**.**
27d50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
27d60 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f  nd_zeroblob() ro
27d70 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c  utine binds a BL
27d80 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74  OB of length N t
27d90 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64  hat.** is filled
27da0 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e   with zeroes.  ^
27db0 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
27dc0 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
27dd0 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
27de0 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
27df0 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77  hold its size) w
27e00 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67  hile it is being
27e10 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a   processed..** Z
27e20 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74  eroblobs are int
27e30 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61  ended to serve a
27e40 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  s placeholders f
27e50 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a  or BLOBs whose.*
27e60 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74  * content is lat
27e70 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67  er written using
27e80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
27e90 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
27ea0 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72  ntal BLOB I/O] r
27eb0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e  outines..** ^A n
27ec0 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f  egative value fo
27ed0 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72  r the zeroblob r
27ee0 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f  esults in a zero
27ef0 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a  -length BLOB..**
27f00 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74  .** ^If any of t
27f10 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
27f20 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  *() routines are
27f30 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
27f40 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66  ULL pointer.** f
27f50 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
27f60 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77   statement] or w
27f70 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73  ith a prepared s
27f80 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69  tatement for whi
27f90 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  ch.** [sqlite3_s
27fa0 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20  tep()] has been 
27fb0 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65  called more rece
27fc0 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74  ntly than [sqlit
27fd0 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20  e3_reset()],.** 
27fe0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69  then the call wi
27ff0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
28000 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61  E_MISUSE].  If a
28010 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ny sqlite3_bind_
28020 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73  ().** routine is
28030 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61   passed a [prepa
28040 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
28050 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e  hat has been fin
28060 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72  alized, the.** r
28070 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
28080 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
28090 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
280a0 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
280b0 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
280c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
280d0 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55  ] routine..** ^U
280e0 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
280f0 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
28100 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
28110 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
28120 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65  nd_* routines re
28130 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
28140 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61   on success or a
28150 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  n.** [error code
28160 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f  ] if anything go
28170 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53  es wrong..** ^[S
28180 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
28190 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
281a0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
281b0 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
281c0 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f  ge.  ^[SQLITE_NO
281d0 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64  MEM] is returned
281e0 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69   if malloc() fai
281f0 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ls..**.** See al
28200 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
28210 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
28220 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
28230 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
28240 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _name()], and [s
28250 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
28260 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
28270 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
28280 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
28290 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
282a0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
282b0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
282c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
282d0 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
282e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
282f0 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74  uble);.int sqlit
28300 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
28310 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
28320 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
28330 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
28340 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
28350 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
28360 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
28370 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
28380 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20  tmt*, int);.int 
28390 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
283a0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
283b0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
283c0 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
283d0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
283e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
283f0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
28400 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
28410 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
28420 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
28430 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
28440 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
28450 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
28460 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
28470 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
28480 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
28490 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
284a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
284b0 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
284c0 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
284d0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
284e0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66  can be used to f
284f0 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
28500 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  f [SQL parameter
28510 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70  s].** in a [prep
28520 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
28530 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73    SQL parameters
28540 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74   are tokens of t
28550 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20  he.** form "?", 
28560 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20  "?NNN", ":AAA", 
28570 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41  "$AAA", or "@AAA
28580 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a  " that serve as.
28590 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  ** placeholders 
285a0 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20  for values that 
285b0 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  are [sqlite3_bin
285c0 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a  d_blob | bound].
285d0 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  ** to the parame
285e0 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20  ters at a later 
285f0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  time..**.** ^(Th
28600 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61  is routine actua
28610 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20  lly returns the 
28620 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72  index of the lar
28630 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29  gest (rightmost)
28640 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46  .** parameter. F
28650 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
28660 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
28670 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
28680 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  o the.** number 
28690 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  of unique parame
286a0 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
286b0 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
286c0 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a   form are used,.
286d0 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20  ** there may be 
286e0 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
286f0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
28700 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
28710 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
28720 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
28730 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
28740 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a  er_name()], and.
28750 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
28760 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
28770 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
28780 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
28790 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  er_count(sqlite3
287a0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
287b0 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
287c0 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74  f A Host Paramet
287d0 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  er.**.** ^The sq
287e0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
287f0 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69  eter_name(P,N) i
28800 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
28810 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
28820 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61  the N-th [SQL pa
28830 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
28840 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28850 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c  ent] P..** ^(SQL
28860 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
28870 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f  he form "?NNN" o
28880 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
28890 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
288a0 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63  have a name whic
288b0 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20  h is the string 
288c0 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
288d0 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
288e0 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69  AAA".** respecti
288f0 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65  vely..** In othe
28900 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69  r words, the ini
28910 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20  tial ":" or "$" 
28920 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a  or "@" or "?".**
28930 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20   is included as 
28940 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65  part of the name
28950 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65  .)^.** ^Paramete
28960 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
28970 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
28980 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
28990 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61  ave no name.** a
289a0 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20  nd are referred 
289b0 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22  to as "nameless"
289c0 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70   or "anonymous p
289d0 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a  arameters"..**.*
289e0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73  * ^The first hos
289f0 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  t parameter has 
28a00 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e  an index of 1, n
28a10 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ot 0..**.** ^If 
28a20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f  the value N is o
28a30 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
28a40 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d  f the N-th param
28a50 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
28a60 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
28a70 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68  s returned.  ^Th
28a80 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
28a90 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
28aa0 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  n UTF-8 encoding
28ab0 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
28ac0 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
28ad0 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
28ae0 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
28af0 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
28b00 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a  repare16()] or.*
28b10 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
28b20 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
28b30 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
28b40 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
28b50 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
28b60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
28b70 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
28b80 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
28b90 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
28ba0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
28bb0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
28bc0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
28bd0 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
28be0 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
28bf0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
28c00 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
28c10 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
28c20 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74   Name.**.** ^Ret
28c30 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
28c40 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
28c50 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
28c60 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78  .  ^The.** index
28c70 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
28c80 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20  is suitable for 
28c90 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e  use as the secon
28ca0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
28cb0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
28cc0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
28cd0 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a  d()].  ^A zero.*
28ce0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  * is returned if
28cf0 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72   no matching par
28d00 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e  ameter is found.
28d10 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
28d20 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65  .** name must be
28d30 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20   given in UTF-8 
28d40 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67  even if the orig
28d50 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a  inal statement.*
28d60 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66  * was prepared f
28d70 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20  rom UTF-16 text 
28d80 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
28d90 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
28da0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
28db0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
28dc0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
28dd0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
28de0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
28df0 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
28e00 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
28e10 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
28e20 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
28e30 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
28e40 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
28e50 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
28e60 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
28e70 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
28e80 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
28e90 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
28ea0 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74  ment.**.** ^Cont
28eb0 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75  rary to the intu
28ec0 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b  ition of many, [
28ed0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
28ee0 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a   does not reset.
28ef0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
28f00 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64  bind_blob | bind
28f10 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70  ings] on a [prep
28f20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
28f30 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f  .** ^Use this ro
28f40 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61  utine to reset a
28f50 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  ll host paramete
28f60 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69  rs to NULL..*/.i
28f70 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  nt sqlite3_clear
28f80 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
28f90 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
28fa0 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
28fb0 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20  r Of Columns In 
28fc0 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a  A Result Set.**.
28fd0 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e  ** ^Return the n
28fe0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
28ff0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
29000 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  et returned by t
29010 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
29020 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69  statement]. ^Thi
29030 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
29040 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20  s 0 if pStmt is 
29050 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  an SQL.** statem
29060 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  ent that does no
29070 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66  t return data (f
29080 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55  or example an [U
29090 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53  PDATE])..**.** S
290a0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
290b0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a  3_data_count()].
290c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
290d0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69  olumn_count(sqli
290e0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
290f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29100 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20  F: Column Names 
29110 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
29120 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
29130 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
29140 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74   name assigned t
29150 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  o a particular c
29160 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  olumn.** in the 
29170 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
29180 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
29190 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  nt.  ^The sqlite
291a0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a  3_column_name().
291b0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
291c0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
291d0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
291e0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
291f0 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
29200 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
29210 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
29220 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
29230 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
29240 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66   string.  ^The f
29250 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
29260 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
29270 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68  statement].** th
29280 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
29290 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
292a0 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e  ment. ^The secon
292b0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
292c0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d  he.** column num
292d0 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d  ber.  ^The leftm
292e0 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75  ost column is nu
292f0 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mber 0..**.** ^T
29300 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
29310 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
29320 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
29330 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
29340 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20  tatement].** is 
29350 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
29360 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
29370 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
29380 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
29390 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
293a0 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
293b0 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
293c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
293d0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
293e0 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
293f0 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a  he next call to.
29400 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
29410 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
29420 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
29430 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  6() on the same 
29440 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  column..**.** ^I
29450 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
29460 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
29470 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
29480 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
29490 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
294a0 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
294b0 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
294c0 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
294d0 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
294e0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
294f0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
29500 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  f a result colum
29510 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  n is the value o
29520 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73  f the "AS" claus
29530 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f  e for.** that co
29540 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69  lumn, if there i
29550 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20  s an AS clause. 
29560 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
29570 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65  AS clause.** the
29580 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
29590 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70  e column is unsp
295a0 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20  ecified and may 
295b0 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f  change from.** o
295c0 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ne release of SQ
295d0 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74  Lite to the next
295e0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
295f0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
29600 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
29610 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73  t*, int N);.cons
29620 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
29630 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71  column_name16(sq
29640 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
29650 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
29660 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20  3REF: Source Of 
29670 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20  Data In A Query 
29680 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  Result.**.** ^Th
29690 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f  ese routines pro
296a0 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20  vide a means to 
296b0 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61  determine the da
296c0 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
296d0 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75  nd.** table colu
296e0 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f  mn that is the o
296f0 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69  rigin of a parti
29700 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c  cular result col
29710 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43  umn in.** [SELEC
29720 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  T] statement..**
29730 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
29740 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61  e database or ta
29750 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61  ble or column ca
29760 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  n be returned as
29770 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46  .** either a UTF
29780 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  -8 or UTF-16 str
29790 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61  ing.  ^The _data
297a0 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
297b0 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
297c0 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
297d0 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
297e0 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
297f0 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
29800 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
29810 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
29820 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  olumn name..** ^
29830 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
29840 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ing is valid unt
29850 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  il the [prepared
29860 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
29870 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e  estroyed.** usin
29880 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
29890 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
298a0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
298b0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
298c0 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20  * reprepared by 
298d0 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
298e0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
298f0 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  )] for a particu
29900 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e  lar run.** or un
29910 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66  til the same inf
29920 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75  ormation is requ
29930 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69  ested.** again i
29940 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e  n a different en
29950 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54  coding..**.** ^T
29960 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65  he names returne
29970 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e  d are the origin
29980 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61  al un-aliased na
29990 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61  mes of the.** da
299a0 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
299b0 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
299c0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
299d0 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e  ment to these in
299e0 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70  terfaces is a [p
299f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29a00 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  t]..** ^These fu
29a10 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69  nctions return i
29a20 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
29a30 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20   the Nth result 
29a40 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
29a50 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  by.** the statem
29a60 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ent, where N is 
29a70 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
29a80 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
29a90 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20   ^The left-most 
29aa0 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e  column is column
29ab0 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75   0 for these rou
29ac0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  tines..**.** ^If
29ad0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
29ae0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
29af0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20  statement is an 
29b00 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a  expression or.**
29b10 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73   subquery and is
29b20 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61   not a column va
29b30 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66  lue, then all of
29b40 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
29b50 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e   return.** NULL.
29b60 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
29b70 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75   might also retu
29b80 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d  rn NULL if a mem
29b90 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
29ba0 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20  rror.** occurs. 
29bb0 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65   ^Otherwise, the
29bc0 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  y return the nam
29bd0 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65  e of the attache
29be0 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  d database, tabl
29bf0 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20  e,.** or column 
29c00 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c  that query resul
29c10 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74  t column was ext
29c20 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a  racted from..**.
29c30 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20  ** ^As with all 
29c40 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49  other SQLite API
29c50 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e  s, those whose n
29c60 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31  ames end with "1
29c70 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46  6" return.** UTF
29c80 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69  -16 encoded stri
29c90 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65  ngs and the othe
29ca0 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  r functions retu
29cb0 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  rn UTF-8..**.** 
29cc0 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20  ^These APIs are 
29cd0 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
29ce0 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
29cf0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
29d00 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
29d10 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
29d20 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
29d30 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a  essor symbol..**
29d40 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
29d50 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
29d60 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
29d70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67  hese routines ag
29d80 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a  ainst the same.*
29d90 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
29da0 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  ment and column 
29db0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
29dc0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
29dd0 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e  s are.** undefin
29de0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ed..**.** If two
29df0 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
29e00 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
29e10 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
29e20 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
29e30 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61  me | column meta
29e40 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d  data interfaces]
29e50 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
29e60 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29e70 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74  ment] and result
29e80 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68   column.** at th
29e90 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
29ea0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
29eb0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63   undefined..*/.c
29ec0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
29ed0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
29ee0 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  se_name(sqlite3_
29ef0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
29f00 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
29f10 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
29f20 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
29f30 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
29f40 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
29f50 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
29f60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
29f70 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
29f80 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
29f90 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c  table_name16(sql
29fa0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
29fb0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
29fc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
29fd0 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  in_name(sqlite3_
29fe0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
29ff0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2a000 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
2a010 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2a020 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
2a030 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
2a040 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41  ed Datatype Of A
2a050 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
2a060 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20  .** ^(The first 
2a070 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b  parameter is a [
2a080 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a090 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  nt]..** If this 
2a0a0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
2a0b0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2a0c0 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f  t and the Nth co
2a0d0 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72  lumn of the.** r
2a0e0 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73  eturned result s
2a0f0 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45  et of that [SELE
2a100 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63  CT] is a table c
2a110 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a  olumn (not an.**
2a120 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
2a130 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68  ubquery) then th
2a140 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20  e declared type 
2a150 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20  of the table.** 
2a160 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e  column is return
2a170 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e  ed.)^  ^If the N
2a180 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
2a190 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61   result set is a
2a1a0 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
2a1b0 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65  or subquery, the
2a1c0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
2a1d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2a1e0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2a1f0 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20  tring is always 
2a200 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a  UTF-8 encoded..*
2a210 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70  *.** ^(For examp
2a220 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61  le, given the da
2a230 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a  tabase schema:.*
2a240 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c  *.** CREATE TABL
2a250 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29  E t1(c1 VARIANT)
2a260 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ;.**.** and the 
2a270 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d  following statem
2a280 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
2a290 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54  ed:.**.** SELECT
2a2a0 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d   c1 + 1, c1 FROM
2a2b0 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20   t1;.**.** this 
2a2c0 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65  routine would re
2a2d0 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20  turn the string 
2a2e0 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68  "VARIANT" for th
2a2f0 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a  e second result.
2a300 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29  ** column (i==1)
2a310 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69  , and a NULL poi
2a320 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72  nter for the fir
2a330 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  st result column
2a340 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a   (i==0).)^.**.**
2a350 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79   ^SQLite uses dy
2a360 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74  namic run-time t
2a370 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74  yping.  ^So just
2a380 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d   because a colum
2a390 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64  n.** is declared
2a3a0 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61   to contain a pa
2a3b0 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f  rticular type do
2a3c0 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74  es not mean that
2a3d0 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f   the.** data sto
2a3e0 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75  red in that colu
2a3f0 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63  mn is of the dec
2a400 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c  lared type.  SQL
2a410 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67  ite is.** strong
2a420 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68  ly typed, but th
2a430 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61  e typing is dyna
2a440 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20  mic not static. 
2a450 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73   ^Type.** is ass
2a460 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64  ociated with ind
2a470 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20  ividual values, 
2a480 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e  not with the con
2a490 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20  tainers.** used 
2a4a0 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61  to hold those va
2a4b0 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  lues..*/.const c
2a4c0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2a4d0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
2a4e0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2a4f0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2a500 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
2a510 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73  type16(sqlite3_s
2a520 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
2a530 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c  * CAPI3REF: Eval
2a540 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74  uate An SQL Stat
2a550 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65  ement.**.** Afte
2a560 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
2a570 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65  atement] has bee
2a580 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  n prepared using
2a590 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69   either.** [sqli
2a5a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2a5b0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
2a5c0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
2a5d0 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61   one of the lega
2a5e0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
2a5f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a600 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
2a610 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
2a620 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
2a630 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f  must be called o
2a640 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
2a650 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65   to evaluate the
2a660 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
2a670 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
2a680 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
2a690 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
2a6a0 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65  p() interface de
2a6b0 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  pend.** on wheth
2a6c0 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  er the statement
2a6d0 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73   was prepared us
2a6e0 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76  ing the newer "v
2a6f0 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  2" interface.** 
2a700 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a710 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
2a720 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2a730 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72  ()] or the older
2a740 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2a750 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72  face [sqlite3_pr
2a760 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
2a770 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2a780 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
2a790 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20  the.** new "v2" 
2a7a0 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
2a7b0 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
2a7c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
2a7d0 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
2a7e0 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
2a7f0 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
2a800 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  pported..**.** ^
2a810 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
2a820 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
2a830 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
2a840 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
2a850 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _BUSY],.** [SQLI
2a860 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
2a870 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
2a880 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
2a890 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e  TE_MISUSE]..** ^
2a8a0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
2a8b0 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
2a8c0 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c  the other [resul
2a8d0 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b  t codes] or.** [
2a8e0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
2a8f0 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20  codes] might be 
2a900 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c  returned as well
2a910 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
2a920 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
2a930 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
2a940 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
2a950 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
2a960 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
2a970 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
2a980 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74   its job.  ^If t
2a990 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2a9a0 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72  a [COMMIT].** or
2a9b0 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20   occurs outside 
2a9c0 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  of an explicit t
2a9d0 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
2a9e0 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74   you can retry t
2a9f0 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  he.** statement.
2aa00 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
2aa10 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d  nt is not a [COM
2aa20 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20  MIT] and occurs 
2aa30 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70  within an.** exp
2aa40 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
2aa50 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c  n then you shoul
2aa60 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74  d rollback the t
2aa70 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72  ransaction befor
2aa80 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e  e.** continuing.
2aa90 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2aaa0 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
2aab0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
2aac0 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
2aad0 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
2aae0 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
2aaf0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
2ab00 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
2ab10 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
2ab20 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
2ab30 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
2ab40 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
2ab50 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
2ab60 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
2ab70 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
2ab80 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
2ab90 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51  **.** ^If the SQ
2aba0 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
2abb0 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
2abc0 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
2abd0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a  n [SQLITE_ROW].*
2abe0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  * is returned ea
2abf0 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
2ac00 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
2ac10 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  dy for processin
2ac20 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  g by the.** call
2ac30 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
2ac40 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
2ac50 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e  sing the [column
2ac60 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2ac70 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
2ac80 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
2ac90 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
2aca0 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
2acb0 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  f data..**.** ^[
2acc0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
2acd0 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
2ace0 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
2acf0 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
2ad00 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
2ad10 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
2ad20 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
2ad30 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
2ad40 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
2ad50 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
2ad60 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
2ad70 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
2ad80 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
2ad90 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c  ..** ^With the l
2ada0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
2adb0 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
2adc0 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72   error code (for
2add0 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51   example,.** [SQ
2ade0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
2adf0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
2ae00 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
2ae10 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
2ae20 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
2ae30 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
2ae40 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2ae50 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ] on the.** [pre
2ae60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2ae70 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  .  ^In the "v2" 
2ae80 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
2ae90 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
2aea0 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
2aeb0 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
2aec0 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
2aed0 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
2aee0 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
2aef0 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
2af00 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
2af10 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
2af20 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
2af30 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
2af40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2af50 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
2af60 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
2af70 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
2af80 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
2af90 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
2afa0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
2afb0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
2afc0 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
2afd0 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
2afe0 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
2aff0 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
2b000 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2b010 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
2b020 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
2b030 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
2b040 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
2b050 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46  in time..**.** F
2b060 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20  or all versions 
2b070 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20  of SQLite up to 
2b080 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e  and including 3.
2b090 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74  6.23.1, a call t
2b0a0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  o.** [sqlite3_re
2b0b0 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69  set()] was requi
2b0c0 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  red after sqlite
2b0d0 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65  3_step() returne
2b0e0 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74  d anything.** ot
2b0f0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
2b100 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79  _ROW] before any
2b110 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
2b120 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c  cation of.** sql
2b130 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61  ite3_step().  Fa
2b140 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74  ilure to reset t
2b150 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
2b160 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20  ement using .** 
2b170 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2b180 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  ] would result i
2b190 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  n an [SQLITE_MIS
2b1a0 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d  USE] return from
2b1b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
2b1c0 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76  ().  But after v
2b1d0 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c  ersion 3.6.23.1,
2b1e0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2b1f0 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67  began.** calling
2b200 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2b210 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  )] automatically
2b220 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73   in this circums
2b230 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20  tance rather.** 
2b240 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b  than returning [
2b250 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
2b260 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e   This is not con
2b270 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74  sidered a compat
2b280 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b  ibility.** break
2b290 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70   because any app
2b2a0 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76  lication that ev
2b2b0 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53  er receives an S
2b2c0 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72  QLITE_MISUSE err
2b2d0 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20  or.** is broken 
2b2e0 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  by definition.  
2b2f0 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  The [SQLITE_OMIT
2b300 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70  _AUTORESET] comp
2b310 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a  ile-time option.
2b320 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ** can be used t
2b330 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65  o restore the le
2b340 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a  gacy behavior..*
2b350 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e  *.** <b>Goofy In
2b360 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f  terface Alert:</
2b370 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  b> In the legacy
2b380 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
2b390 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a  sqlite3_step().*
2b3a0 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74  * API always ret
2b3b0 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65  urns a generic e
2b3c0 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49  rror code, [SQLI
2b3d0 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f  TE_ERROR], follo
2b3e0 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f  wing any.** erro
2b3f0 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  r other than [SQ
2b400 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b  LITE_BUSY] and [
2b410 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
2b420 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a   You must call.*
2b430 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2b440 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2b450 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f  finalize()] in o
2b460 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65  rder to find one
2b470 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69   of the.** speci
2b480 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
2b490 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65  ] that better de
2b4a0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
2b4b0 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74  r..** We admit t
2b4c0 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f  hat this is a go
2b4d0 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65  ofy design.  The
2b4e0 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65   problem has bee
2b4f0 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20  n fixed.** with 
2b500 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2b510 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70  ce.  If you prep
2b520 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20  are all of your 
2b530 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
2b540 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  * using either [
2b550 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2b560 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
2b570 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2b580 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  ] instead.** of 
2b590 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
2b5a0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
2b5b0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2b5c0 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61  are16()] interfa
2b5d0 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ces,.** then the
2b5e0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b   more specific [
2b5f0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65  error codes] are
2b600 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
2b610 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ly.** by sqlite3
2b620 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73  _step().  The us
2b630 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e  e of the "v2" in
2b640 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
2b650 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  mended..*/.int s
2b660 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
2b670 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2b680 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2b690 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2b6a0 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a  n a result set.*
2b6b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2b6c0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2b6d0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2b6e0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2b6f0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a  columns in the.*
2b700 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  * current row of
2b710 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2b720 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
2b730 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49  tement] P..** ^I
2b740 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  f prepared state
2b750 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20  ment P does not 
2b760 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61  have results rea
2b770 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  dy to return.** 
2b780 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68  (via calls to th
2b790 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
2b7a0 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  n_int | sqlite3_
2b7b0 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a  column_*()] of.*
2b7c0 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68  * interfaces) th
2b7d0 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  en sqlite3_data_
2b7e0 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73  count(P) returns
2b7f0 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69   0..** ^The sqli
2b800 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2b810 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72  ) routine also r
2b820 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73  eturns 0 if P is
2b830 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
2b840 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b850 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
2b860 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
2b870 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
2b880 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2b890 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
2b8a0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44  turned [SQLITE_D
2b8b0 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  ONE].  ^The sqli
2b8c0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2b8d0 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e  ).** will return
2b8e0 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65   non-zero if pre
2b8f0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73  vious call to [s
2b900 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
2b910 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c  returned.** [SQL
2b920 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74  ITE_ROW], except
2b930 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20   in the case of 
2b940 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72  the [PRAGMA incr
2b950 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a  emental_vacuum].
2b960 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61  ** where it alwa
2b970 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20  ys returns zero 
2b980 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20  since each step 
2b990 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74  of that multi-st
2b9a0 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74  ep.** pragma ret
2b9b0 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f  urns 0 columns o
2b9c0 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65  f data..**.** Se
2b9d0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2b9e0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
2b9f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2ba00 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
2ba10 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2ba20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ba30 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
2ba40 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  tatypes.** KEYWO
2ba50 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
2ba60 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76  .**.** ^(Every v
2ba70 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68  alue in SQLite h
2ba80 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66  as one of five f
2ba90 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74  undamental datat
2baa0 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ypes:.**.** <ul>
2bab0 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
2bac0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
2bad0 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45  * <li> 64-bit IE
2bae0 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  EE floating poin
2baf0 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e  t number.** <li>
2bb00 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20   string.** <li> 
2bb10 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c  BLOB.** <li> NUL
2bb20 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  L.** </ul>)^.**.
2bb30 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2bb40 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72  ts are codes for
2bb50 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74   each of those t
2bb60 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ypes..**.** Note
2bb70 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45   that the SQLITE
2bb80 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77  _TEXT constant w
2bb90 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20  as also used in 
2bba0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
2bbb0 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65  .** for a comple
2bbc0 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d  tely different m
2bbd0 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72  eaning.  Softwar
2bbe0 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  e that links aga
2bbf0 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c  inst both.** SQL
2bc00 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e  ite version 2 an
2bc10 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
2bc20 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51   3 should use SQ
2bc30 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a  LITE3_TEXT, not.
2bc40 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
2bc50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2bc60 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
2bc70 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
2bc80 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
2bc90 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
2bca0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2bcb0 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
2bcc0 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
2bcd0 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
2bce0 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
2bcf0 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
2bd00 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
2bd10 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
2bd20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
2bd30 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c  3REF: Result Val
2bd40 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79  ues From A Query
2bd50 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
2bd60 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2bd70 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  ctions}.**.** Th
2bd80 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ese routines for
2bd90 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65  m the "result se
2bda0 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  t" interface..**
2bdb0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2bdc0 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  nes return infor
2bdd0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73  mation about a s
2bde0 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
2bdf0 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72  the current.** r
2be00 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71  esult row of a q
2be10 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79  uery.  ^In every
2be20 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
2be30 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
2be40 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
2be50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2be60 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
2be70 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
2be80 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
2be90 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
2bea0 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
2beb0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2bec0 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
2bed0 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
2bee0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
2bef0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
2bf00 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
2bf10 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
2bf20 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
2bf30 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54   be returned. ^T
2bf40 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
2bf50 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
2bf60 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
2bf70 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75  ex 0..** ^The nu
2bf80 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2bf90 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61  in the result ca
2bfa0 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
2bfb0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2bfc0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
2bfd0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  ]..**.** If the 
2bfe0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
2bff0 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
2c000 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
2c010 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
2c020 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
2c030 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2c040 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
2c050 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
2c060 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
2c070 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
2c080 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
2c090 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
2c0a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2c0b0 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
2c0c0 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
2c0d0 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
2c0e0 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
2c0f0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2c100 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
2c110 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
2c120 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
2c130 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2c140 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
2c150 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2c160 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2c170 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2c180 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
2c190 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
2c1a0 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
2c1b0 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
2c1c0 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
2c1d0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2c1e0 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
2c1f0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
2c200 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2c210 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
2c220 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
2c230 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
2c240 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
2c250 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
2c260 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
2c270 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
2c280 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2c290 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2c2a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2c2b0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75  olumn_type() rou
2c2c0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2c2d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
2c2e0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
2c2f0 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
2c300 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
2c310 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
2c320 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65  column.  ^The re
2c330 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20  turned value is 
2c340 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
2c350 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  NTEGER],.** [SQL
2c360 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
2c370 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49  ITE_TEXT], [SQLI
2c380 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51  TE_BLOB], or [SQ
2c390 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65  LITE_NULL].  The
2c3a0 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
2c3b0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2c3c0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f  lumn_type() is o
2c3d0 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69  nly meaningful i
2c3e0 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e  f no type.** con
2c3f0 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63  versions have oc
2c400 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69  curred as descri
2c410 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65  bed below.  Afte
2c420 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  r a type convers
2c430 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75  ion,.** the valu
2c440 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
2c450 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2c460 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
2c470 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72  .  Future.** ver
2c480 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
2c490 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62  may change the b
2c4a0 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
2c4b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2c4c0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
2c4d0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  type conversion.
2c4e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
2c4f0 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
2c500 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
2c510 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2c520 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
2c530 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
2c540 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2c550 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
2c560 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
2c570 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2c580 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
2c590 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
2c5a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2c5b0 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
2c5c0 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
2c5d0 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
2c5e0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2c5f0 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
2c600 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
2c610 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
2c620 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c630 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20  bytes() uses.** 
2c640 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2c650 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
2c660 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
2c670 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64  UTF-8 string and
2c680 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
2c690 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2c6a0 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
2c6b0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2c6c0 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
2c6d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c6e0 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a  ytes() returns z
2c6f0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ero..**.** ^If t
2c700 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
2c710 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74  LOB or UTF-16 st
2c720 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
2c730 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2c740 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  es16().** routin
2c750 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2c760 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2c770 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
2c780 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2c790 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
2c7a0 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  -8 string, then 
2c7b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c7c0 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74  ytes16() convert
2c7d0 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
2c7e0 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68  to UTF-16 and th
2c7f0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
2c800 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
2c810 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2c820 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
2c830 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
2c840 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2c850 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
2c860 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2c870 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
2c880 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31  value to a UTF-1
2c890 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  6 string and ret
2c8a0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
2c8b0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2c8c0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
2c8d0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2c8e0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
2c8f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2c900 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  16() returns zer
2c910 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61  o..**.** ^The va
2c920 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
2c930 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2c940 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a  _bytes()] and .*
2c950 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2c960 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20  n_bytes16()] do 
2c970 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20  not include the 
2c980 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73  zero terminators
2c990 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f   at the end.** o
2c9a0 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e  f the string.  ^
2c9b0 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65  For clarity: the
2c9c0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
2c9d0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
2c9e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
2c9f0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
2ca00 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61  umn_bytes16()] a
2ca10 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  re the number of
2ca20 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65  .** bytes in the
2ca30 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65   string, not the
2ca40 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
2ca50 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74  cters..**.** ^St
2ca60 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
2ca70 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2ca80 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69  _text() and sqli
2ca90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2caa0 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70  6(),.** even emp
2cab0 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20  ty strings, are 
2cac0 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
2cad0 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65  inated.  ^The re
2cae0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72  turn.** value fr
2caf0 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  om sqlite3_colum
2cb00 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a  n_blob() for a z
2cb10 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
2cb20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2cb30 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62  r..**.** ^The ob
2cb40 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
2cb50 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2cb60 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a  _value()] is an.
2cb70 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
2cb80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2cb90 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f  bject.  An unpro
2cba0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2cbb0 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d  alue object.** m
2cbc0 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
2cbd0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69  with [sqlite3_bi
2cbe0 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  nd_value()] and 
2cbf0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2cc00 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20  value()]..** If 
2cc10 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
2cc20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2cc30 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2cc40 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
2cc50 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2cc60 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74  s used in any ot
2cc70 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69  her way, includi
2cc80 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72  ng calls.** to r
2cc90 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
2cca0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
2ccb0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
2ccc0 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
2ccd0 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
2cce0 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20  _bytes()], then 
2ccf0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
2cd00 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2cd10 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2cd20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
2cd30 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65  rt the value whe
2cd40 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20  re appropriate. 
2cd50 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65   ^For.** example
2cd60 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61  , if the interna
2cd70 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
2cd80 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20   is FLOAT and a 
2cd90 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69  text result.** i
2cda0 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71  s requested, [sq
2cdb0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
2cdc0 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  ] is used intern
2cdd0 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20  ally to perform 
2cde0 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  the.** conversio
2cdf0 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  n automatically.
2ce00 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e    ^(The followin
2ce10 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20  g table details 
2ce20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a  the conversions.
2ce30 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c  ** that are appl
2ce40 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ied:.**.** <bloc
2ce50 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
2ce60 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
2ce70 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e   <tr><th> Intern
2ce80 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  al<br>Type <th> 
2ce90 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70  Requested<br>Typ
2cea0 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69  e <th>  Conversi
2ceb0 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
2cec0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2ced0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52  INTEGER   <td> R
2cee0 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74  esult is 0.** <t
2cef0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2cf00 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2cf10 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e  td> Result is 0.
2cf20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
2cf30 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45  ULL    <td>   TE
2cf40 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  XT    <td> Resul
2cf50 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
2cf60 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
2cf70 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
2cf80 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
2cf90 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
2cfa0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
2cfb0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f  TEGER  <td>  FLO
2cfc0 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
2cfd0 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20  rt from integer 
2cfe0 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  to float.** <tr>
2cff0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
2d000 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2d010 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
2d020 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  g of the integer
2d030 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2d040 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f  EGER  <td>   BLO
2d050 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
2d060 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a  s INTEGER->TEXT.
2d070 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2d080 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  AT   <td> INTEGE
2d090 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
2d0a0 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69   from float to i
2d0b0 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
2d0c0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
2d0d0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2d0e0 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
2d0f0 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20  of the float.** 
2d100 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2d110 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2d120 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c   <td> Same as FL
2d130 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  OAT->TEXT.** <tr
2d140 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
2d150 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2d160 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a  d> Use atoi().**
2d170 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
2d180 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
2d190 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28    <td> Use atof(
2d1a0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
2d1b0 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
2d1c0 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
2d1d0 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
2d1e0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
2d1f0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
2d200 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
2d210 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a  en use atoi().**
2d220 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
2d230 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
2d240 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
2d250 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
2d260 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
2d270 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
2d280 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2d290 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
2d2a0 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
2d2b0 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
2d2c0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
2d2d0 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61  *.** The table a
2d2e0 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72  bove makes refer
2d2f0 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64  ence to standard
2d300 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74   C library funct
2d310 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61  ions atoi().** a
2d320 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69  nd atof().  SQLi
2d330 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c  te does not real
2d340 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e  ly use these fun
2d350 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20  ctions.  It has 
2d360 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76  its.** own equiv
2d370 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72  alent internal r
2d380 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74  outines.  The at
2d390 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20  oi() and atof() 
2d3a0 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65  names are.** use
2d3b0 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66  d in the table f
2d3c0 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62  or brevity and b
2d3d0 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20  ecause they are 
2d3e0 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74  familiar to most
2d3f0 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72  .** C programmer
2d400 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
2d410 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e  at when type con
2d420 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20  versions occur, 
2d430 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2d440 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61  d by prior.** ca
2d450 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2d460 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71  olumn_blob(), sq
2d470 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2d480 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  t(), and/or.** s
2d490 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2d4a0 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e  xt16() may be in
2d4b0 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79  validated..** Ty
2d4c0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
2d4d0 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
2d4e0 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
2d4f0 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
2d500 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
2d510 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
2d520 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2d530 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
2d540 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2d550 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
2d560 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2d570 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
2d580 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
2d590 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
2d5a0 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74  t.**      need t
2d5b0 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
2d5c0 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a  e string.</li>.*
2d5d0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
2d5e0 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
2d5f0 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
2d600 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d610 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
2d620 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d630 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
2d640 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
2d650 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
2d660 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
2d670 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  F-16.</li>.** <l
2d680 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2d690 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36  ontent is UTF-16
2d6a0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
2d6b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2d6c0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2d6d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2d6e0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
2d6f0 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
2d700 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
2d710 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c      to UTF-8.</l
2d720 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
2d730 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  * ^Conversions b
2d740 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
2d750 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
2d760 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
2d770 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
2d780 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
2d790 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
2d7a0 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
2d7b0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
2d7c0 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
2d7d0 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
2d7e0 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20  nter references 
2d7f0 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
2d800 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
2d810 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
2d820 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
2d830 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
2d840 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
2d850 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79  t sometimes they
2d860 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73  .** are not poss
2d870 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
2d880 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
2d890 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
2d8a0 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  idated..**.** Th
2d8b0 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73  e safest and eas
2d8c0 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72  iest to remember
2d8d0 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
2d8e0 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
2d8f0 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
2d900 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
2d910 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ays:.**.** <ul>.
2d920 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
2d930 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
2d940 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
2d950 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2d960 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
2d970 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2d980 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
2d990 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d9a0 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
2d9b0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
2d9c0 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
2d9d0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
2d9e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2d9f0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
2da00 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
2da10 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
2da20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
2da30 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
2da40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2da50 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
2da60 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2da70 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
2da80 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
2da90 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
2daa0 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
2dab0 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
2dac0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
2dad0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2dae0 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
2daf0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
2db00 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
2db10 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
2db20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2db30 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
2db40 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
2db50 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
2db60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2db70 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
2db80 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
2db90 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
2dba0 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
2dbb0 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
2dbc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2dbd0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ()..**.** ^The p
2dbe0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
2dbf0 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
2dc00 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2dc10 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
2dc20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
2dc30 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
2dc40 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
2dc50 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2dc60 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
2dc70 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
2dc80 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f  lled.  ^The memo
2dc90 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
2dca0 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
2dcb0 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72   and BLOBs is fr
2dcc0 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
2dcd0 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62  y.  Do <b>not</b
2dce0 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  > pass the point
2dcf0 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ers returned.** 
2dd00 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2dd10 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
2dd20 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
2dd30 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b  , etc. into.** [
2dd40 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
2dd50 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65  .**.** ^(If a me
2dd60 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2dd70 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
2dd80 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69  ing the evaluati
2dd90 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  on of any.** of 
2dda0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
2ddb0 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  a default value 
2ddc0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
2ddd0 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a  e default value.
2dde0 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65  ** is either the
2ddf0 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20   integer 0, the 
2de00 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
2de10 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20  umber 0.0, or a 
2de20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e  NULL.** pointer.
2de30 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c    Subsequent cal
2de40 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
2de50 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72  rrcode()] will r
2de60 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
2de70 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f  _NOMEM].)^.*/.co
2de80 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2de90 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
2dea0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2deb0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
2dec0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2ded0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2dee0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
2def0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2df00 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74  tes16(sqlite3_st
2df10 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2df20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63  double sqlite3_c
2df30 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c  olumn_double(sql
2df40 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2df50 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2df60 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71  e3_column_int(sq
2df70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2df80 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
2df90 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f  int64 sqlite3_co
2dfa0 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74  lumn_int64(sqlit
2dfb0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2dfc0 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  ol);.const unsig
2dfd0 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
2dfe0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
2dff0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2e000 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f   iCol);.const vo
2e010 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2e020 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  mn_text16(sqlite
2e030 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2e040 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2e050 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69  column_type(sqli
2e060 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2e070 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61  Col);.sqlite3_va
2e080 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  lue *sqlite3_col
2e090 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  umn_value(sqlite
2e0a0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2e0b0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
2e0c0 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50  REF: Destroy A P
2e0d0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2e0e0 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e  t Object.**.** ^
2e0f0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
2e100 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  lize() function 
2e110 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c  is called to del
2e120 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ete a [prepared 
2e130 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
2e140 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2e150 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
2e160 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65   the statement e
2e170 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72  ncountered no er
2e180 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68  rors.** or if th
2e190 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
2e1a0 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61  ever been evalua
2e1b0 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ted, then sqlite
2e1c0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74  3_finalize() ret
2e1d0 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  urns.** SQLITE_O
2e1e0 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  K.  ^If the most
2e1f0 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
2e200 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20  on of statement 
2e210 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a  S failed, then.*
2e220 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  * sqlite3_finali
2e230 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68  ze(S) returns th
2e240 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  e appropriate [e
2e250 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  rror code] or.**
2e260 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
2e270 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
2e280 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
2e290 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63  ize(S) routine c
2e2a0 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
2e2b0 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
2e2c0 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63  .** the life cyc
2e2d0 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  le of [prepared 
2e2e0 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a  statement] S:.**
2e2f0 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e   before statemen
2e300 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c  t S is ever eval
2e310 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20  uated, after.** 
2e320 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c  one or more call
2e330 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
2e340 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72  set()], or after
2e350 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20   any call.** to 
2e360 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2e370 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
2e380 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
2e390 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a  e statement has.
2e3a0 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65  ** completed exe
2e3b0 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  cution..**.** ^I
2e3c0 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
2e3d0 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20  finalize() on a 
2e3e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
2e3f0 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
2e400 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
2e410 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e  ication must fin
2e420 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65  alize every [pre
2e430 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2e440 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f   in order to avo
2e450 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c  id.** resource l
2e460 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67  eaks.  It is a g
2e470 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f  rievous error fo
2e480 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
2e490 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a  n to try to use.
2e4a0 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74  ** a prepared st
2e4b0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
2e4c0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
2e4d0 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66  zed.  Any use of
2e4e0 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73   a prepared.** s
2e4f0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
2e500 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
2e510 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20  ized can result 
2e520 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
2e530 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20  .** undesirable 
2e540 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73  behavior such as
2e550 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68   segfaults and h
2e560 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a  eap corruption..
2e570 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  */.int sqlite3_f
2e580 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
2e590 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2e5a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2e5b0 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
2e5c0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
2e5d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2e5e0 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74  e3_reset() funct
2e5f0 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
2e600 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72   reset a [prepar
2e610 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2e620 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20   object back to 
2e630 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
2e640 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72  e, ready to be r
2e650 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e  e-executed..** ^
2e660 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
2e670 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74  t variables that
2e680 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e   had values boun
2e690 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a  d to them using.
2e6a0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
2e6b0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
2e6c0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49  te3_bind_*() API
2e6d0 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76  ] retain their v
2e6e0 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73  alues..** Use [s
2e6f0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
2e700 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65  dings()] to rese
2e710 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a  t the bindings..
2e720 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
2e730 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
2e740 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74  terface resets t
2e750 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2e760 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63  tement] S.** bac
2e770 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  k to the beginni
2e780 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61  ng of its progra
2e790 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  m..**.** ^If the
2e7a0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2e7b0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2e7c0 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
2e7d0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2e7e0 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65  ement] S returne
2e7f0 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f  d [SQLITE_ROW] o
2e800 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  r [SQLITE_DONE],
2e810 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74  .** or if [sqlit
2e820 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
2e830 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65  never before bee
2e840 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a  n called on S,.*
2e850 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  * then [sqlite3_
2e860 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
2e870 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
2e880 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
2e890 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2e8a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2e8b0 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
2e8c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e8d0 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61  t] S indicated a
2e8e0 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a  n error, then.**
2e8f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2e900 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61  S)] returns an a
2e910 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
2e920 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
2e930 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2e940 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
2e950 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
2e960 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f   the values.** o
2e970 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62  f any [sqlite3_b
2e980 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67  ind_blob|binding
2e990 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61  s] on the [prepa
2e9a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2e9b0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2e9c0 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
2e9d0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2e9e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
2e9f0 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
2ea00 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   SQL Functions.*
2ea10 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e  * KEYWORDS: {fun
2ea20 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
2ea30 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57  outines}.** KEYW
2ea40 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
2ea50 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2ea60 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57  unction}.** KEYW
2ea70 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
2ea80 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2ea90 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
2eaa0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
2eab0 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
2eac0 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f  nown as "functio
2ead0 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
2eae0 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65  nes").** are use
2eaf0 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
2eb00 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
2eb10 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66  ates or to redef
2eb20 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
2eb30 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20  .** of existing 
2eb40 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
2eb50 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
2eb60 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
2eb70 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  es between.** th
2eb80 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2eb90 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
2eba0 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a  ng expected for.
2ebb0 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  ** the second pa
2ebc0 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d  rameter (the nam
2ebd0 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
2ebe0 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29  n being created)
2ebf0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73  .** and the pres
2ec00 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20  ence or absence 
2ec10 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  of a destructor 
2ec20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20  callback for.** 
2ec30 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2ec40 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  data pointer..**
2ec50 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
2ec60 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2ec70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2ec80 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74  tion] to which t
2ec90 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
2eca0 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  on is to be adde
2ecb0 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69  d.  ^If an appli
2ecc0 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65  cation uses more
2ecd0 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61   than one databa
2ece0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
2ecf0 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f   then applicatio
2ed00 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2ed10 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20  nctions must be 
2ed20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68  added.** to each
2ed30 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2ed40 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e  tion separately.
2ed50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
2ed60 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
2ed70 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2ed80 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
2ed90 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a  be created or.**
2eda0 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   redefined.  ^Th
2edb0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
2edc0 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
2edd0 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20  to 255 bytes in 
2ede0 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65  a UTF-8.** repre
2edf0 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75  sentation, exclu
2ee00 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f  sive of the zero
2ee10 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e  -terminator.  ^N
2ee20 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ote that the nam
2ee30 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69  e.** length limi
2ee40 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79  t is in UTF-8 by
2ee50 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74  tes, not charact
2ee60 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62  ers nor UTF-16 b
2ee70 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20  ytes.  .** ^Any 
2ee80 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
2ee90 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  e a function wit
2eea0 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a  h a longer name.
2eeb0 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ** will result i
2eec0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
2eed0 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64  ] being returned
2eee0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
2eef0 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41  rd parameter (nA
2ef00 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  rg).** is the nu
2ef10 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
2ef20 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
2ef30 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
2ef40 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e  gregate takes. ^
2ef50 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
2ef60 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68  r is -1, then th
2ef70 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
2ef80 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
2ef90 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
2efa0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
2efb0 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
2efc0 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62  e limit.** set b
2efd0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
2efe0 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
2eff0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20  FUNCTION_ARG]). 
2f000 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   If the third.**
2f010 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65   parameter is le
2f020 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72  ss than -1 or gr
2f030 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74  eater than 127 t
2f040 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
2f050 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64   is.** undefined
2f060 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
2f070 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
2f080 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
2f090 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49  es what.** [SQLI
2f0a0 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65  TE_UTF8 | text e
2f0b0 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51  ncoding] this SQ
2f0c0 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65  L function prefe
2f0d0 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61  rs for.** its pa
2f0e0 72 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79  rameters.  Every
2f0f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
2f100 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
2f110 74 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72  t be able to wor
2f120 6b 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c  k.** with UTF-8,
2f130 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54   UTF-16le, or UT
2f140 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d  F-16be.  But som
2f150 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2f160 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65  s may be.** more
2f170 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20   efficient with 
2f180 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61  one encoding tha
2f190 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20  n another.  ^An 
2f1a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a  application may.
2f1b0 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
2f1c0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2f1d0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  n() or sqlite3_c
2f1e0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2f1f0 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74  () multiple.** t
2f200 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61  imes with the sa
2f210 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20  me function but 
2f220 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76  with different v
2f230 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65  alues of eTextRe
2f240 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74  p..** ^When mult
2f250 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
2f260 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
2f270 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76   function are av
2f280 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a  ailable, SQLite.
2f290 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65  ** will pick the
2f2a0 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76   one that involv
2f2b0 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
2f2c0 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76  unt of data conv
2f2d0 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  ersion..** If th
2f2e0 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69  ere is only a si
2f2f0 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ngle implementat
2f300 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e  ion which does n
2f310 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78  ot care what tex
2f320 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73  t.** encoding is
2f330 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20   used, then the 
2f340 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
2f350 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54  should be [SQLIT
2f360 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  E_ANY]..**.** ^(
2f370 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
2f380 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
2f390 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
2f3a0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2f3b0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74   of the.** funct
2f3c0 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
2f3d0 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
2f3e0 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ter using [sqlit
2f3f0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
2f400 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69  )^.**.** ^The si
2f410 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64  xth, seventh and
2f420 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65   eighth paramete
2f430 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
2f440 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
2f450 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
2f460 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
2f470 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
2f480 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
2f490 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2f4a0 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20  gate. ^A scalar 
2f4b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
2f4c0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
2f4d0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
2f4e0 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
2f4f0 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e   only; NULL poin
2f500 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73  ters must be pas
2f510 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
2f520 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70   and xFinal.** p
2f530 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61  arameters. ^An a
2f540 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
2f550 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
2f560 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2f570 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
2f580 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
2f590 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65   pointer must be
2f5a0 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
2f5b0 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e  c. ^To delete an
2f5c0 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c   existing.** SQL
2f5d0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
2f5e0 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
2f5f0 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61  L pointers for a
2f600 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
2f610 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  n.** callbacks..
2f620 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e  **.** ^(If the n
2f630 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  inth parameter t
2f640 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
2f650 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69  _function_v2() i
2f660 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74  s not NULL,.** t
2f670 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75  hen it is destru
2f680 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  ctor for the app
2f690 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
2f6a0 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64  inter. .** The d
2f6b0 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76  estructor is inv
2f6c0 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75  oked when the fu
2f6d0 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
2f6e0 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69  d, either by bei
2f6f0 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64  ng.** overloaded
2f700 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74   or when the dat
2f710 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2f720 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54   closes.)^.** ^T
2f730 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
2f740 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66   also invoked if
2f750 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
2f760 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2f770 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69  unction_v2() fai
2f780 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  ls..** ^When the
2f790 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
2f7a0 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74  back of the tent
2f7b0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  h parameter is i
2f7c0 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73  nvoked, it.** is
2f7d0 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65   passed a single
2f7e0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
2f7f0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
2f800 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
2f810 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68  a .** pointer wh
2f820 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74  ich was the fift
2f830 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2f840 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2f850 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  nction_v2()..**.
2f860 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74  ** ^It is permit
2f870 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
2f880 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
2f890 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
2f8a0 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
2f8b0 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
2f8c0 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
2f8d0 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
2f8e0 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
2f8f0 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
2f900 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
2f910 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e  xt encodings.  ^
2f920 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
2f930 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
2f940 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20  ation that most 
2f950 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
2f960 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
2f970 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
2f980 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e  tion is used.  ^
2f990 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  A function imple
2f9a0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
2f9b0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a   non-negative.**
2f9c0 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20   nArg parameter 
2f9d0 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63  is a better matc
2f9e0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
2f9f0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2fa00 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74   with.** a negat
2fa10 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75  ive nArg.  ^A fu
2fa20 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
2fa30 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
2fa40 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63  encoding.** matc
2fa50 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  hes the database
2fa60 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62   encoding is a b
2fa70 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74  etter.** match t
2fa80 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
2fa90 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
2faa0 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20  g is different. 
2fab0 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e   .** ^A function
2fac0 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
2fad0 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
2fae0 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c  s between UTF16l
2faf0 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a  e and UTF16be.**
2fb00 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74   is a closer mat
2fb10 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
2fb20 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
2fb30 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
2fb40 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55   is.** between U
2fb50 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a  TF8 and UTF16..*
2fb60 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66  *.** ^Built-in f
2fb70 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
2fb80 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65  overloaded by ne
2fb90 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  w application-de
2fba0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e  fined functions.
2fbb0 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69  .**.** ^An appli
2fbc0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2fbd0 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69  unction is permi
2fbe0 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68  tted to call oth
2fbf0 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
2fc00 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65  erfaces.  Howeve
2fc10 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75  r, such calls mu
2fc20 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20  st not.** close 
2fc30 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2fc40 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61  nection nor fina
2fc50 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68  lize or reset th
2fc60 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  e prepared.** st
2fc70 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68  atement in which
2fc80 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
2fc90 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74   running..*/.int
2fca0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2fcb0 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
2fcc0 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
2fcd0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
2fce0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
2fcf0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
2fd00 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
2fd10 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
2fd20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2fd30 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2fd40 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2fd50 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
2fd60 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2fd70 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2fd80 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
2fd90 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2fda0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2fdb0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2fdc0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
2fdd0 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
2fde0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
2fdf0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
2fe00 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
2fe10 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
2fe20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
2fe30 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2fe40 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2fe50 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
2fe60 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2fe70 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2fe80 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2fe90 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
2fea0 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
2feb0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2fec0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73  function_v2(.  s
2fed0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
2fee0 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
2fef0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
2ff00 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
2ff10 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
2ff20 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
2ff30 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
2ff40 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2ff50 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2ff60 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
2ff70 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2ff80 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2ff90 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
2ffa0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2ffb0 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  t*),.  void(*xDe
2ffc0 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
2ffd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ffe0 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73  : Text Encodings
2fff0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
30000 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
30010 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
30020 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
30030 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
30040 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
30050 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
30060 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
30070 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a  TF8           1.
30080 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
30090 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a  TF16LE        2.
300a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
300b0 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a  TF16BE        3.
300c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
300d0 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20  TF16          4 
300e0 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65     /* Use native
300f0 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23   byte order */.#
30100 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
30110 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20  Y            5  
30120 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
30130 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c  ate_function onl
30140 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
30150 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
30160 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74  D  8    /* sqlit
30170 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
30180 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a  ion only */../*.
30190 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70  ** CAPI3REF: Dep
301a0 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e  recated Function
301b0 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a  s.** DEPRECATED.
301c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
301d0 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65  tions are [depre
301e0 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65  cated].  In orde
301f0 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a  r to maintain.**
30200 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
30210 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c  tibility with ol
30220 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20  der code, these 
30230 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e  functions contin
30240 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70  ue .** to be sup
30250 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72  ported.  However
30260 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  , new applicatio
30270 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a  ns should avoid.
30280 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  ** the use of th
30290 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
302a0 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67  To help encourag
302b0 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69  e people to avoi
302c0 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65  d.** using these
302d0 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61   functions, we a
302e0 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20  re not going to 
302f0 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68  tell you what th
30300 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65  ey do..*/.#ifnde
30310 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45  f SQLITE_OMIT_DE
30320 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f  PRECATED.SQLITE_
30330 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
30340 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
30350 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63  _count(sqlite3_c
30360 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45  ontext*);.SQLITE
30370 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
30380 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28  sqlite3_expired(
30390 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
303a0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
303b0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72  D int sqlite3_tr
303c0 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28  ansfer_bindings(
303d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73  sqlite3_stmt*, s
303e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
303f0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
30400 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f   int sqlite3_glo
30410 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64  bal_recover(void
30420 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
30430 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65  ATED void sqlite
30440 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70  3_thread_cleanup
30450 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44  (void);.SQLITE_D
30460 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
30470 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61  lite3_memory_ala
30480 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  rm(void(*)(void*
30490 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69  ,sqlite3_int64,i
304a0 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20  nt),.           
304b0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a             void*
304c0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b  ,sqlite3_int64);
304d0 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
304e0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69  API3REF: Obtaini
304f0 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  ng SQL Function 
30500 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73  Parameter Values
30510 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e  .**.** The C-lan
30520 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61  guage implementa
30530 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63  tion of SQL func
30540 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
30550 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69  ates uses.** thi
30560 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61  s set of interfa
30570 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61  ce routines to a
30580 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65  ccess the parame
30590 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a  ter values on.**
305a0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72   the function or
305b0 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a   aggregate..**.*
305c0 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72  * The xFunc (for
305d0 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e   scalar function
305e0 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72  s) or xStep (for
305f0 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72   aggregates) par
30600 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73  ameters.** to [s
30610 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
30620 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
30630 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
30640 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64  nction16()].** d
30650 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20  efine callbacks 
30660 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
30670 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  he SQL functions
30680 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
30690 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61  .** The 3rd para
306a0 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63  meter to these c
306b0 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61  allbacks is an a
306c0 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
306d0 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65   to.** [protecte
306e0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
306f0 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65   objects.  There
30700 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33   is one [sqlite3
30710 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
30720 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d  or.** each param
30730 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20  eter to the SQL 
30740 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65  function.  These
30750 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
30760 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74  ed to.** extract
30770 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65   values from the
30780 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
30790 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20   objects..**.** 
307a0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
307b0 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70  ork only with [p
307c0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
307d0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
307e0 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
307f0 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75  to use these rou
30800 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70  tines on an [unp
30810 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
30820 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63  _value].** objec
30830 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  t results in und
30840 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
30850 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
30860 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74  utines work just
30870 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73   like the corres
30880 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20  ponding [column 
30890 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
308a0 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ].** except that
308b0 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73    these routines
308c0 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b   take a single [
308d0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
308e0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a  3_value] object.
308f0 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65  ** pointer inste
30900 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33  ad of a [sqlite3
30910 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20  _stmt*] pointer 
30920 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63  and an integer c
30930 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a  olumn number..**
30940 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30950 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
30960 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
30970 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  ts a UTF-16 stri
30980 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
30990 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
309a0 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
309b0 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  ne.  ^The.** sql
309c0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
309d0 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
309e0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
309f0 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
30a00 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20   extract UTF-16 
30a10 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65  strings as big-e
30a20 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65  ndian and little
30a30 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69  -endian respecti
30a40 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  vely..**.** ^(Th
30a50 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
30a60 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69  numeric_type() i
30a70 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
30a80 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75  s to apply.** nu
30a90 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74  meric affinity t
30aa0 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68  o the value.  Th
30ab0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e  is means that an
30ac0 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d   attempt is.** m
30ad0 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ade to convert t
30ae0 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69  he value to an i
30af0 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69  nteger or floati
30b00 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a  ng point.  If.**
30b10 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69   such a conversi
30b20 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77  on is possible w
30b30 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69  ithout loss of i
30b40 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f  nformation (in o
30b50 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69  ther.** words, i
30b60 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61  f the value is a
30b70 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f   string that loo
30b80 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72  ks like a number
30b90 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ).** then the co
30ba0 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66  nversion is perf
30bb0 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73  ormed.  Otherwis
30bc0 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e no conversion 
30bd0 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b  occurs..** The [
30be0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
30bf0 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72   datatype] after
30c00 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72   conversion is r
30c10 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  eturned.)^.**.**
30c20 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74   Please pay part
30c30 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e  icular attention
30c40 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61   to the fact tha
30c50 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65  t the pointer re
30c60 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
30c70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
30c80 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
30c90 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f  value_text()], o
30ca0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  r.** [sqlite3_va
30cb0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61  lue_text16()] ca
30cc0 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  n be invalidated
30cd0 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74   by a subsequent
30ce0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
30cf0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
30d00 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
30d10 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20  lue_bytes16()], 
30d20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
30d30 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
30d40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
30d50 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  t16()]..**.** Th
30d60 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
30d70 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
30d80 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
30d90 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
30da0 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70  unction that sup
30db0 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74  plied the [sqlit
30dc0 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d  e3_value*] param
30dd0 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  eters..*/.const 
30de0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
30df0 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  lue_blob(sqlite3
30e00 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
30e10 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
30e20 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  s(sqlite3_value*
30e30 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
30e40 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c  alue_bytes16(sql
30e50 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f  ite3_value*);.do
30e60 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  uble sqlite3_val
30e70 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  ue_double(sqlite
30e80 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
30e90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
30ea0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
30eb0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
30ec0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
30ed0 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64(sqlite3_valu
30ee0 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  e*);.const unsig
30ef0 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
30f00 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c  3_value_text(sql
30f10 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
30f20 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
30f30 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73  3_value_text16(s
30f40 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
30f50 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
30f60 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
30f70 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
30f80 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
30f90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
30fa0 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76  xt16be(sqlite3_v
30fb0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
30fc0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73  te3_value_type(s
30fd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
30fe0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
30ff0 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
31000 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31010 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31020 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
31030 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
31040 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65  xt.**.** Impleme
31050 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72  ntations of aggr
31060 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
31070 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20  ons use this.** 
31080 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
31090 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73  ate memory for s
310a0 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
310b0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  te..**.** ^The f
310c0 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71  irst time the sq
310d0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
310e0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
310f0 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a  tine is called .
31100 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ** for a particu
31110 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75  lar aggregate fu
31120 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a  nction, SQLite.*
31130 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66  * allocates N of
31140 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
31150 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  out that memory,
31160 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
31170 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
31180 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e   new memory. ^On
31190 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
311a0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
311b0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
311c0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66  gate_context() f
311d0 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
311e0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
311f0 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  nstance,.** the 
31200 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
31210 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65  eturned.  Sqlite
31220 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
31230 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c  ext() is normall
31240 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65  y.** called once
31250 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61   for each invoca
31260 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65  tion of the xSte
31270 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74  p callback and t
31280 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20  hen one.** last 
31290 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46  time when the xF
312a0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73  inal callback is
312b0 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65   invoked.  ^(Whe
312c0 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a  n no rows match.
312d0 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  ** an aggregate 
312e0 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70  query, the xStep
312f0 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  () callback of t
31300 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
31310 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ction.** impleme
31320 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72  ntation is never
31330 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e   called and xFin
31340 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65  al() is called e
31350 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20  xactly once..** 
31360 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20  In those cases, 
31370 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
31380 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68  e_context() migh
31390 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20  t be called for 
313a0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d  the.** first tim
313b0 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46  e from within xF
313c0 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  inal().)^.**.** 
313d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67  ^The sqlite3_agg
313e0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
313f0 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,N) routine retu
31400 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
31410 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73  er .** when firs
31420 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73  t called if N is
31430 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
31440 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69  ual to zero or i
31450 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  f a memory.** al
31460 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63  locate error occ
31470 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  urs..**.** ^(The
31480 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65   amount of space
31490 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
314a0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
314b0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a  context(C,N) is.
314c0 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  ** determined by
314d0 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
314e0 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73   on first succes
314f0 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e  sful call.  Chan
31500 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ging the.** valu
31510 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71  e of N in subseq
31520 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
31530 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
31540 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a  ontext() within.
31550 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  ** the same aggr
31560 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
31570 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74  nstance will not
31580 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f   resize the memo
31590 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
315a0 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20  .)^  Within the 
315b0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c  xFinal callback,
315c0 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79   it is customary
315d0 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69   to set.** N=0 i
315e0 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  n calls to sqlit
315f0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
31600 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61  text(C,N) so tha
31610 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65  t no .** pointle
31620 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ss memory alloca
31630 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a  tions occur..**.
31640 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d  ** ^SQLite autom
31650 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
31660 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
31670 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ted by .** sqlit
31680 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
31690 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20  text() when the 
316a0 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
316b0 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
316c0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
316d0 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63  eter must be a c
316e0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
316f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
31700 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
31710 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
31720 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
31730 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74  er.** to the xSt
31740 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  ep or xFinal cal
31750 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
31760 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
31770 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
31780 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
31790 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
317a0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
317b0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
317c0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
317d0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
317e0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
317f0 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
31800 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
31810 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  ntext(sqlite3_co
31820 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74  ntext*, int nByt
31830 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  es);../*.** CAPI
31840 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20  3REF: User Data 
31850 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
31860 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31870 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74  _user_data() int
31880 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
31890 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
318a0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
318b0 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70   the pUserData p
318c0 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74  arameter (the 5t
318d0 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  h parameter).** 
318e0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
318f0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
31900 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
31910 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
31920 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
31930 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
31940 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
31950 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
31960 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
31970 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
31980 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
31990 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
319a0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
319b0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
319c0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
319d0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
319e0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
319f0 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69  3_user_data(sqli
31a00 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
31a10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31a20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
31a30 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ion For Function
31a40 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
31a50 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
31a60 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61  handle() interfa
31a70 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
31a80 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
31a90 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61  ter to the [data
31aa0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
31ab0 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65   (the 1st parame
31ac0 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
31ad0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
31ae0 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
31af0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
31b00 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
31b10 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
31b20 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
31b30 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
31b40 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
31b50 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69  unction..*/.sqli
31b60 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e  te3 *sqlite3_con
31b70 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73  text_db_handle(s
31b80 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
31b90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31ba0 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69  F: Function Auxi
31bb0 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a  liary Data.**.**
31bc0 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
31bd0 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  wo functions may
31be0 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c   be used by scal
31bf0 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ar SQL functions
31c00 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65   to.** associate
31c10 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61   metadata with a
31c20 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20  rgument values. 
31c30 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  If the same valu
31c40 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a  e is passed to.*
31c50 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63  * multiple invoc
31c60 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
31c70 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
31c80 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65  during query exe
31c90 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a  cution, under.**
31ca0 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e   some circumstan
31cb0 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74  ces the associat
31cc0 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20  ed metadata may 
31cd0 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68  be preserved. Th
31ce0 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65  is may.** be use
31cf0 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  d, for example, 
31d00 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72  to add a regular
31d10 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63  -expression matc
31d20 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66  hing scalar.** f
31d30 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d  unction. The com
31d40 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66  piled version of
31d50 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
31d60 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65  ression is store
31d70 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61  d as.** metadata
31d80 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
31d90 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70   the SQL value p
31da0 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67  assed as the reg
31db0 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a  ular expression.
31dc0 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65  ** pattern.  The
31dd0 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61   compiled regula
31de0 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
31df0 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75   be reused on mu
31e00 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61  ltiple.** invoca
31e10 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
31e20 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68  e function so th
31e30 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  at the original 
31e40 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a  pattern string.*
31e50 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  * does not need 
31e60 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64  to be recompiled
31e70 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74   on each invocat
31e80 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
31e90 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
31ea0 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
31eb0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
31ec0 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74  r to the metadat
31ed0 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
31ee0 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  by the sqlite3_s
31ef0 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e  et_auxdata() fun
31f00 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e  ction with the N
31f10 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76  th argument.** v
31f20 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c  alue to the appl
31f30 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
31f40 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f  function. ^If no
31f50 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65   metadata has be
31f60 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20  en ever.** been 
31f70 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20  set for the Nth 
31f80 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
31f90 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20  function, or if 
31fa0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
31fb0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61  g.** function pa
31fc0 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e  rameter has chan
31fd0 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65  ged since the me
31fe0 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c  ta-data was set,
31ff0 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33  .** then sqlite3
32000 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72  _get_auxdata() r
32010 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
32020 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
32030 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
32040 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
32050 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61  e saves the meta
32060 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  data.** pointed 
32070 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61  to by its 3rd pa
32080 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d  rameter as the m
32090 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20  etadata for the 
320a0 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  N-th.** argument
320b0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
320c0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
320d0 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e  tion.  Subsequen
320e0 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  t.** calls to sq
320f0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
32100 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e  a() might return
32110 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69   this data, if i
32120 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65  t has.** not bee
32130 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20  n destroyed..** 
32140 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55  ^If it is not NU
32150 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  LL, SQLite will 
32160 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
32170 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  uctor.** functio
32180 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34  n given by the 4
32190 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
321a0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
321b0 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20  ata() on.** the 
321c0 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68  metadata when th
321d0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
321e0 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
321f0 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72  er changes.** or
32200 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74   when the SQL st
32210 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65  atement complete
32220 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  s, whichever com
32230 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20  es first..**.** 
32240 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74  SQLite is free t
32250 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72  o call the destr
32260 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d  uctor and drop m
32270 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a  etadata on any.*
32280 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61  * parameter of a
32290 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61  ny function at a
322a0 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f  ny time.  ^The o
322b0 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73  nly guarantee is
322c0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73   that.** the des
322d0 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20  tructor will be 
322e0 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68  called before th
322f0 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72  e metadata is dr
32300 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  opped..**.** ^(I
32310 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61  n practice, meta
32320 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65  data is preserve
32330 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69  d between functi
32340 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20  on calls for.** 
32350 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74  expressions that
32360 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74   are constant at
32370 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54   compile time. T
32380 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74  his includes lit
32390 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61  eral.** values a
323a0 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e  nd [parameters].
323b0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )^.**.** These r
323c0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
323d0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
323e0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
323f0 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20  hich.** the SQL 
32400 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
32410 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
32420 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
32430 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
32440 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64  t*, int N);.void
32450 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
32460 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
32470 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f  text*, int N, vo
32480 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f  id*, void (*)(vo
32490 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  id*));.../*.** C
324a0 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e  API3REF: Constan
324b0 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63  ts Defining Spec
324c0 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42  ial Destructor B
324d0 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68  ehavior.**.** Th
324e0 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20  ese are special 
324f0 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64  values for the d
32500 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69  estructor that i
32510 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  s passed in as t
32520 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75  he.** final argu
32530 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73  ment to routines
32540 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72   like [sqlite3_r
32550 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20  esult_blob()].  
32560 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74  ^If the destruct
32570 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
32580 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
32590 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
325a0 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
325b0 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
325c0 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
325d0 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
325e0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
325f0 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68   destroyed.  ^Th
32600 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e  e.** SQLITE_TRAN
32610 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e  SIENT value mean
32620 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
32630 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63  nt will likely c
32640 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20  hange in.** the 
32650 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20  near future and 
32660 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75  that SQLite shou
32670 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20  ld make its own 
32680 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a  private copy of.
32690 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62  ** the content b
326a0 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
326b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64  .**.** The typed
326c0 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20  ef is necessary 
326d0 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70  to work around p
326e0 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61  roblems in certa
326f0 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c  in.** C++ compil
32700 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74  ers.  See ticket
32710 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64   #2191..*/.typed
32720 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
32730 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
32740 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
32750 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
32760 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
32770 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
32780 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
32790 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
327a0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
327b0 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
327c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
327d0 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
327e0 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
327f0 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  on.**.** These r
32800 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
32810 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72   by the xFunc or
32820 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
32830 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d  s that.** implem
32840 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ent SQL function
32850 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
32860 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  See.** [sqlit
32870 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
32880 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
32890 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
328a0 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61  on16()].** for a
328b0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
328c0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
328d0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72  se functions wor
328e0 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65  k very much like
328f0 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20   the [parameter 
32900 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20  binding] family 
32910 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  of.** functions 
32920 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c  used to bind val
32930 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61  ues to host para
32940 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72  meters in prepar
32950 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  ed statements..*
32960 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b  * Refer to the [
32970 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64  SQL parameter] d
32980 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
32990 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
329a0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  rmation..**.** ^
329b0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
329c0 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
329d0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
329e0 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
329f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
32a00 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
32a10 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
32a20 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
32a30 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
32a40 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
32a50 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
32a60 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
32a70 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
32a80 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ird parameter..*
32a90 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
32aa0 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
32ab0 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73  b() interfaces s
32ac0 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  et the result of
32ad0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
32ae0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
32af0 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f  tion to be a BLO
32b00 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c  B containing all
32b10 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61   zero.** bytes a
32b20 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  nd N bytes in si
32b30 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  ze, where N is t
32b40 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
32b50 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  2nd parameter..*
32b60 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
32b70 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
32b80 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
32b90 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
32ba0 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
32bb0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
32bc0 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61  ion to be a floa
32bd0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
32be0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
32bf0 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
32c00 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
32c10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32c20 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
32c30 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
32c40 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63  ) functions.** c
32c50 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ause the impleme
32c60 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  nted SQL functio
32c70 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78  n to throw an ex
32c80 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c  ception..** ^SQL
32c90 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
32ca0 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
32cb0 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
32cc0 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
32cd0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
32ce0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
32cf0 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
32d00 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
32d10 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
32d20 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70    ^SQLite interp
32d30 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  rets the error.*
32d40 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  * message string
32d50 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
32d60 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20  sult_error() as 
32d70 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a  UTF-8. ^SQLite.*
32d80 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  * interprets the
32d90 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
32da0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32db0 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20  r16() as UTF-16 
32dc0 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74  in native.** byt
32dd0 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68  e order.  ^If th
32de0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
32df0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
32e00 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
32e10 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
32e20 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65  _error16() is ne
32e30 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
32e40 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20  te takes as the 
32e50 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
32e60 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72   all text up thr
32e70 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
32e80 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
32e90 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20  * ^If the third 
32ea0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
32eb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32ec0 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  r() or.** sqlite
32ed0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
32ee0 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  () is non-negati
32ef0 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
32f00 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a  akes that many.*
32f10 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  * bytes (not cha
32f20 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68  racters) from th
32f30 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
32f40 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  as the error mes
32f50 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  sage..** ^The sq
32f60 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32f70 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
32f80 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
32f90 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61  ).** routines ma
32fa0 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70  ke a private cop
32fb0 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d  y of the error m
32fc0 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f  essage text befo
32fd0 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72  re.** they retur
32fe0 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  n.  Hence, the c
32ff0 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
33000 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f  can deallocate o
33010 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20  r.** modify the 
33020 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20  text after they 
33030 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68  return without h
33040 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  arm..** ^The sql
33050 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33060 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f  r_code() functio
33070 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72  n changes the er
33080 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75  ror code.** retu
33090 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  rned by SQLite a
330a0 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e  s a result of an
330b0 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63   error in a func
330c0 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75  tion.  ^By defau
330d0 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  lt,.** the error
330e0 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f   code is SQLITE_
330f0 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65  ERROR.  ^A subse
33100 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
33110 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33120 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
33130 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
33140 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65  6() resets the e
33150 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c  rror code to SQL
33160 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a  ITE_ERROR..**.**
33170 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
33180 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
33190 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  g() interface ca
331a0 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
331b0 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  hrow an.** error
331c0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
331d0 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
331e0 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f  B is too long to
331f0 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a   represent..**.*
33200 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
33210 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
33220 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  m() interface ca
33230 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
33240 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  hrow an.** error
33250 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
33260 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
33270 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a  tion failed..**.
33280 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33290 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74  result_int() int
332a0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
332b0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
332c0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
332d0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
332e0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32  ion to be the 32
332f0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
33300 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
33310 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
33320 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
33330 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
33340 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65  nt64() interface
33350 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
33360 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
33370 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
33380 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
33390 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73   be the 64-bit s
333a0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
333b0 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
333c0 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
333d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
333e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
333f0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
33400 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
33410 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
33420 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
33430 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
33440 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
33450 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33460 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f  text(), sqlite3_
33470 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c  result_text16(),
33480 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
33490 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61  lt_text16le(), a
334a0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
334b0 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74  t_text16be() int
334c0 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74  erfaces.** set t
334d0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
334e0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
334f0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
33500 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74  ion to be.** a t
33510 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68  ext string which
33520 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20   is represented 
33530 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  as UTF-8, UTF-16
33540 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
33550 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  er,.** UTF-16 li
33560 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20  ttle endian, or 
33570 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61  UTF-16 big endia
33580 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
33590 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65  .** ^SQLite take
335a0 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c  s the text resul
335b0 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69  t from the appli
335c0 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74  cation from.** t
335d0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
335e0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
335f0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
33600 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20  erfaces..** ^If 
33610 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
33620 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
33630 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
33640 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
33650 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51  egative, then SQ
33660 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c  Lite takes resul
33670 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20  t text from the 
33680 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  2nd parameter.**
33690 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
336a0 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
336b0 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72  r..** ^If the 3r
336c0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
336d0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
336e0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
336f0 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67  es.** is non-neg
33700 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d  ative, then as m
33710 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63  any bytes (not c
33720 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68  haracters) of th
33730 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65  e text.** pointe
33740 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20  d to by the 2nd 
33750 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61  parameter are ta
33760 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69  ken as the appli
33770 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a  cation-defined.*
33780 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c  * function resul
33790 74 2e 20 20 49 66 20 74 68 65 20 33 72 64 20 70  t.  If the 3rd p
337a0 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d  arameter is non-
337b0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
337c0 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65  t.** must be the
337d0 20 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74   byte offset int
337e0 6f 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65  o the string whe
337f0 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
33800 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61  nator would.** a
33810 70 70 65 61 72 20 69 66 20 74 68 65 20 73 74 72  ppear if the str
33820 69 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65  ing where NUL te
33830 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
33840 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
33850 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
33860 20 73 74 72 69 6e 67 20 61 74 20 61 20 62 79 74   string at a byt
33870 65 20 6f 66 66 73 65 74 20 74 68 61 74 20 69 73  e offset that is
33880 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 76   less than the v
33890 61 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a  alue of the 3rd.
338a0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  ** parameter, th
338b0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  en the resulting
338c0 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e   string will con
338d0 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55  tain embedded NU
338e0 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65  Ls and the.** re
338f0 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69  sult of expressi
33900 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e  ons operating on
33910 20 73 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d   strings with em
33920 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75  bedded NULs is u
33930 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66  ndefined..** ^If
33940 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
33950 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
33960 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
33970 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
33980 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
33990 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c  lob is a non-NUL
339a0 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
339b0 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61  SQLite calls tha
339c0 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73  t.** function as
339d0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
339e0 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  on the text or B
339f0 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20  LOB result when 
33a00 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68  it has.** finish
33a10 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
33a20 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  sult..** ^If the
33a30 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
33a40 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
33a50 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
33a60 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73  faces or to.** s
33a70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
33a80 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
33a90 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
33aa0 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53  E_STATIC, then S
33ab0 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73  QLite.** assumes
33ac0 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f   that the text o
33ad0 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73  r BLOB result is
33ae0 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61   in constant spa
33af0 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a  ce and does not.
33b00 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74  ** copy the cont
33b10 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d  ent of the param
33b20 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20  eter nor call a 
33b30 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
33b40 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65  e content.** whe
33b50 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  n it has finishe
33b60 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
33b70 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
33b80 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
33b90 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
33ba0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
33bb0 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
33bc0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
33bd0 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
33be0 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52  nstant SQLITE_TR
33bf0 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20  ANSIENT.** then 
33c00 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
33c10 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c  opy of the resul
33c20 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74  t into space obt
33c30 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72  ained from.** fr
33c40 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
33c50 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20  oc()] before it 
33c60 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
33c70 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
33c80 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
33c90 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
33ca0 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
33cb0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
33cc0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
33cd0 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20  e a copy the.** 
33ce0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
33cf0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
33d00 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ct specified by 
33d10 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
33d20 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  r.  ^The.** sqli
33d30 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
33d40 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  () interface mak
33d50 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
33d60 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
33d70 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20  .** so that the 
33d80 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
33d90 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
33da0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63   parameter may c
33db0 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64  hange or.** be d
33dc0 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72  eallocated after
33dd0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33de0 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20  value() returns 
33df0 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
33e00 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73   ^A [protected s
33e10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
33e20 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20  ject may always 
33e30 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e  be used where an
33e40 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
33e50 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
33e60 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72  object is requir
33e70 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a  ed, so either.**
33e80 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65   kind of [sqlite
33e90 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
33ea0 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68  can be used with
33eb0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
33ec0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20  .**.** If these 
33ed0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
33ee0 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  led from within 
33ef0 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68  the different th
33f00 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65  read.** than the
33f10 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20   one containing 
33f20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
33f30 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
33f40 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a   that received.*
33f50 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  * the [sqlite3_c
33f60 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c  ontext] pointer,
33f70 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
33f80 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76   undefined..*/.v
33f90 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
33fa0 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  lt_blob(sqlite3_
33fb0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
33fc0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
33fd0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
33fe0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
33ff0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
34000 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65  context*, double
34010 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
34020 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c  result_error(sql
34030 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
34040 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29  onst char*, int)
34050 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
34060 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71  esult_error16(sq
34070 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
34080 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
34090 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
340a0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
340b0 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  big(sqlite3_cont
340c0 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
340d0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
340e0 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63  _nomem(sqlite3_c
340f0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
34100 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
34110 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33  ror_code(sqlite3
34120 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
34130 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
34140 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33  sult_int(sqlite3
34150 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
34160 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
34170 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74  sult_int64(sqlit
34180 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
34190 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69  ite3_int64);.voi
341a0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
341b0 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f  _null(sqlite3_co
341c0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
341d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
341e0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
341f0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
34200 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
34210 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
34220 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
34230 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
34240 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
34250 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
34260 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
34270 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
34280 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6le(sqlite3_cont
34290 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
342a0 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
342b0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
342c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
342d0 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16be(sqlite3_con
342e0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
342f0 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
34300 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
34310 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
34320 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ue(sqlite3_conte
34330 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  xt*, sqlite3_val
34340 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ue*);.void sqlit
34350 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
34360 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
34370 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  xt*, int n);../*
34380 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
34390 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69  fine New Collati
343a0 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a  ng Sequences.**.
343b0 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
343c0 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c  ons add, remove,
343d0 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f   or modify a [co
343e0 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61  llation] associa
343f0 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
34400 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
34410 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
34420 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
34430 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
34440 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
34450 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46  llation is a UTF
34460 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72  -8 string.** for
34470 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
34480 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20  collation() and 
34490 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
344a0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a  ollation_v2().**
344b0 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74   and a UTF-16 st
344c0 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
344d0 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71  yte order for sq
344e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
344f0 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e  lation16()..** ^
34500 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20  Collation names 
34510 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75  that compare equ
34520 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  al according to 
34530 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d  [sqlite3_strnicm
34540 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73  p()] are.** cons
34550 69 64 65 72 65 64 20 74 6f 20 62 65 20 74 68 65  idered to be the
34560 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a   same name..**.*
34570 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20 61 72  * ^(The third ar
34580 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70  gument (eTextRep
34590 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66  ) must be one of
345a0 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a   the constants:.
345b0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
345c0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a  [SQLITE_UTF8],.*
345d0 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
345e0 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  TF16LE],.** <li>
345f0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
34600 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
34610 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a  TE_UTF16], or.**
34620 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
34630 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a  F16_ALIGNED]..**
34640 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65   </ul>)^.** ^The
34650 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65   eTextRep argume
34660 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  nt determines th
34670 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74  e encoding of st
34680 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20  rings passed.** 
34690 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
346a0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
346b0 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a  ck, xCallback..*
346c0 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55  * ^The [SQLITE_U
346d0 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54  TF16] and [SQLIT
346e0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
346f0 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78   values for eTex
34700 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74  tRep.** force st
34710 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31  rings to be UTF1
34720 36 20 77 69 74 68 20 6e 61 74 69 76 65 20 62 79  6 with native by
34730 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68  te order..** ^Th
34740 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  e [SQLITE_UTF16_
34750 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66  ALIGNED] value f
34760 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f 72 63  or eTextRep forc
34770 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65  es strings to be
34780 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65  gin.** on an eve
34790 6e 20 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a  n byte address..
347a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
347b0 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67  h argument, pArg
347c0 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74  , is an applicat
347d0 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
347e0 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 0a   that is passed.
347f0 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ** through as th
34800 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
34810 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
34820 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
34830 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ack..**.** ^The 
34840 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  fifth argument, 
34850 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20  xCallback, is a 
34860 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63  pointer to the c
34870 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
34880 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20  n..** ^Multiple 
34890 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
348a0 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69 73  ons can be regis
348b0 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
348c0 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a  same name but.**
348d0 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
348e0 65 54 65 78 74 52 65 70 20 70 61 72 61 6d 65 74  eTextRep paramet
348f0 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77  ers and SQLite w
34900 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76 65  ill use whicheve
34910 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  r.** function re
34920 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74  quires the least
34930 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
34940 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a  transformation..
34950 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c  ** ^If the xCall
34960 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73  back argument is
34970 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63   NULL then the c
34980 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
34990 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e  n is.** deleted.
349a0 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c    ^When all coll
349b0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
349c0 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20  having the same 
349d0 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64  name are deleted
349e0 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74  ,.** that collat
349f0 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  ion is no longer
34a00 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e   usable..**.** ^
34a10 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
34a20 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20  nction callback 
34a30 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
34a40 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41  a copy of the pA
34a50 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  rg .** applicati
34a60 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  on data pointer 
34a70 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74 72  and with two str
34a80 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f  ings in the enco
34a90 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a  ding specified.*
34aa0 2a 20 62 79 20 74 68 65 20 65 54 65 78 74 52 65  * by the eTextRe
34ab0 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65  p argument.  The
34ac0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
34ad0 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20  ion must return 
34ae0 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68  an.** integer th
34af0 61 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  at is negative, 
34b00 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76  zero, or positiv
34b10 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73  e.** if the firs
34b20 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73  t string is less
34b30 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c   than, equal to,
34b40 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
34b50 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20   the second,.** 
34b60 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41  respectively.  A
34b70 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
34b80 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20  ion must always 
34b90 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20  return the same 
34ba0 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20  answer.** given 
34bb0 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e  the same inputs.
34bc0 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65    If two or more
34bd0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
34be0 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74 65  ions are registe
34bf0 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61  red.** to the sa
34c00 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d  me collation nam
34c10 65 20 28 75 73 69 6e 67 20 64 69 66 66 65 72 65  e (using differe
34c20 6e 74 20 65 54 65 78 74 52 65 70 20 76 61 6c 75  nt eTextRep valu
34c30 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20  es) then all.** 
34c40 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65 71 75  must give an equ
34c50 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77  ivalent answer w
34c60 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68  hen invoked with
34c70 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69   equivalent stri
34c80 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c  ngs..** The coll
34c90 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
34ca0 75 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c  ust obey the fol
34cb0 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65  lowing propertie
34cc0 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72  s for all.** str
34cd0 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43  ings A, B, and C
34ce0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
34cf0 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65  <li> If A==B the
34d00 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20  n B==A..** <li> 
34d10 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43  If A==B and B==C
34d20 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c   then A==C..** <
34d30 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48  li> If A&lt;B TH
34d40 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c  EN B&gt;A..** <l
34d50 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64  i> If A&lt;B and
34d60 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c   B&lt;C then A&l
34d70 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  t;C..** </ol>.**
34d80 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69  .** If a collati
34d90 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c  ng function fail
34da0 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f  s any of the abo
34db0 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61  ve constraints a
34dc0 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61  nd that.** colla
34dd0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
34de0 20 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64    registered and
34df0 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20   used, then the 
34e00 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
34e10 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  te.** is undefin
34e20 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
34e30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
34e40 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72  llation_v2() wor
34e50 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
34e60 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
34e70 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61  ().** with the a
34e80 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65  ddition that the
34e90 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61   xDestroy callba
34ea0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
34eb0 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68   pArg when.** th
34ec0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
34ed0 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e  tion is deleted.
34ee0 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66  .** ^Collating f
34ef0 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c  unctions are del
34f00 65 74 65 64 20 77 68 65 6e 20 74 68 65 79 20 61  eted when they a
34f10 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  re overridden by
34f20 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20   later.** calls 
34f30 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  to the collation
34f40 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69   creation functi
34f50 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a  ons or when the.
34f60 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
34f70 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73  nection] is clos
34f80 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
34f90 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_close()]..**.*
34fa0 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20  * ^The xDestroy 
34fb0 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e  callback is <u>n
34fc0 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66  ot</u> called if
34fd0 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   the .** sqlite3
34fe0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
34ff0 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20  n_v2() function 
35000 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74  fails.  Applicat
35010 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65  ions that invoke
35020 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
35030 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
35040 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  ) with a non-NUL
35050 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d  L xDestroy argum
35060 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63  ent should .** c
35070 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
35080 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65  code and dispose
35090 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
350a0 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
350b0 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72  .** themselves r
350c0 61 74 68 65 72 20 74 68 61 6e 20 65 78 70 65 63  ather than expec
350d0 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64  ting SQLite to d
350e0 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20  eal with it for 
350f0 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73  them..** This is
35100 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
35110 65 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69  every other SQLi
35120 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  te interface.  T
35130 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79  he inconsistency
35140 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e   .** is unfortun
35150 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62  ate but cannot b
35160 65 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75  e changed withou
35170 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77  t breaking backw
35180 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69  ards .** compati
35190 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65  bility..**.** Se
351a0 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65  e also:  [sqlite
351b0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
351c0 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ed()] and [sqlit
351d0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
351e0 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  ded16()]..*/.int
351f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
35200 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c  collation(.  sql
35210 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
35220 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
35230 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
35240 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
35250 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
35260 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
35270 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
35280 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  id*).);.int sqli
35290 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
352a0 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
352b0 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
352c0 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
352d0 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
352e0 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
352f0 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
35300 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
35310 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
35320 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
35330 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
35340 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
35350 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a  te_collation16(.
35360 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
35370 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65  onst void *zName
35380 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
35390 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
353a0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
353b0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
353c0 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
353d0 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  t void*).);../*.
353e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
353f0 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61  lation Needed Ca
35400 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
35410 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74  o avoid having t
35420 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63  o register all c
35430 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
35440 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61  es before a data
35450 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75  base.** can be u
35460 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61  sed, a single ca
35470 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
35480 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
35490 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64  d with the.** [d
354a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
354b0 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  on] to be invoke
354c0 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e  d whenever an un
354d0 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
354e0 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73  n.** sequence is
354f0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
35500 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
35510 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  n is registered 
35520 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
35530 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
35540 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65  ed() API,.** the
35550 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74  n it is passed t
35560 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65  he names of unde
35570 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  fined collation 
35580 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72  sequences as str
35590 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20  ings.** encoded 
355a0 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71  in UTF-8. ^If sq
355b0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
355c0 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73  needed16() is us
355d0 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73  ed,.** the names
355e0 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55   are passed as U
355f0 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65  TF-16 in machine
35600 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
35610 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  er..** ^A call t
35620 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f  o either functio
35630 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 65  n replaces the e
35640 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f  xisting collatio
35650 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63  n-needed callbac
35660 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20  k..**.** ^(When 
35670 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
35680 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72  invoked, the fir
35690 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  st argument pass
356a0 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20  ed is a copy.** 
356b0 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  of the second ar
356c0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
356d0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
356e0 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  ed() or.** sqlit
356f0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
35700 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65  ded16().  The se
35710 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
35720 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
35730 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68   connection.  Th
35740 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
35750 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
35760 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54  TE_UTF8], [SQLIT
35770 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f  E_UTF16BE],.** o
35780 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
35790 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74  E], indicating t
357a0 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c  he most desirabl
357b0 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f  e form of the co
357c0 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
357d0 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  nce function req
357e0 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72  uired.  The four
357f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
35800 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
35810 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c  ** required coll
35820 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29  ation sequence.)
35830 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ^.**.** The call
35840 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68  back function sh
35850 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68  ould register th
35860 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74  e desired collat
35870 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
35880 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
35890 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69  lation()], [sqli
358a0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
358b0 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  tion16()], or.**
358c0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
358d0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d  _collation_v2()]
358e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
358f0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
35900 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  d(.  sqlite3*, .
35910 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64    void*, .  void
35920 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
35930 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c  3*,int eTextRep,
35940 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a  const char*).);.
35950 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
35960 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a  ation_needed16(.
35970 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
35980 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28  oid*,.  void(*)(
35990 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69  void*,sqlite3*,i
359a0 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73  nt eTextRep,cons
359b0 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66  t void*).);..#if
359c0 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43  def SQLITE_HAS_C
359d0 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  ODEC./*.** Speci
359e0 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61  fy the key for a
359f0 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61  n encrypted data
35a00 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74  base.  This rout
35a10 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ine should be.**
35a20 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66   called right af
35a30 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ter sqlite3_open
35a40 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ()..**.** The co
35a50 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
35a60 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
35a70 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
35a80 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
35a90 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
35aa0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79  .int sqlite3_key
35ab0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
35ac0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35ad0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
35ae0 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
35af0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
35b00 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
35b10 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29   /* The key */.)
35b20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20  ;../*.** Change 
35b30 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70  the key on an op
35b40 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66  en database.  If
35b50 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
35b60 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20  abase is not.** 
35b70 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20  encrypted, this 
35b80 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63  routine will enc
35b90 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65  rypt it.  If pNe
35ba0 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c  w==0 or nNew==0,
35bb0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
35bc0 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a   is decrypted..*
35bd0 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
35be0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
35bf0 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
35c00 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
35c10 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
35c20 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
35c30 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20  sqlite3_rekey(. 
35c40 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
35c50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35c60 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
35c70 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
35c80 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
35c90 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
35ca0 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a   The new key */.
35cb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  );../*.** Specif
35cc0 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
35cd0 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20 64   key for a SEE d
35ce0 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73  atabase.  Unless
35cf0 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20   .** activated, 
35d00 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20  none of the SEE 
35d10 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f  routines will wo
35d20 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  rk..*/.void sqli
35d30 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65  te3_activate_see
35d40 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
35d50 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20  zPassPhrase     
35d60 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e     /* Activation
35d70 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65   phrase */.);.#e
35d80 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c  ndif..#ifdef SQL
35d90 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44  ITE_ENABLE_CEROD
35da0 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
35db0 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65  he activation ke
35dc0 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61  y for a CEROD da
35dd0 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20  tabase.  Unless 
35de0 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e  .** activated, n
35df0 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44  one of the CEROD
35e00 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77   routines will w
35e10 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ork..*/.void sql
35e20 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65  ite3_activate_ce
35e30 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  rod(.  const cha
35e40 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
35e50 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
35e60 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
35e70 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
35e80 41 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64  API3REF: Suspend
35e90 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41   Execution For A
35ea0 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a   Short Time.**.*
35eb0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c  * The sqlite3_sl
35ec0 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  eep() function c
35ed0 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e  auses the curren
35ee0 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70  t thread to susp
35ef0 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a  end execution.**
35f00 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20   for at least a 
35f10 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
35f20 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64  econds specified
35f30 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65   in its paramete
35f40 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  r..**.** If the 
35f50 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
35f60 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72   does not suppor
35f70 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73  t sleep requests
35f80 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65   with.** millise
35f90 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75  cond time resolu
35fa0 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74  tion, then the t
35fb0 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e  ime will be roun
35fc0 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65  ded up to.** the
35fd0 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e   nearest second.
35fe0 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   The number of m
35ff0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
36000 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  leep actually.**
36010 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20   requested from 
36020 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
36030 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64  stem is returned
36040 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
36050 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20  implements this 
36060 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c  interface by cal
36070 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28  ling the xSleep(
36080 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74  ).** method of t
36090 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
360a0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
360b0 20 20 49 66 20 74 68 65 20 78 53 6c 65 65 70 28    If the xSleep(
360c0 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74  ) method.** of t
360d0 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69  he default VFS i
360e0 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
360f0 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20  d correctly, or 
36100 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  not implemented 
36110 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20  at.** all, then 
36120 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
36130 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20  sqlite3_sleep() 
36140 6d 61 79 20 64 65 76 69 61 74 65 20 66 72 6f 6d  may deviate from
36150 20 74 68 65 20 64 65 73 63 72 69 70 74 69 6f 6e   the description
36160 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 65 76 69  .** in the previ
36170 6f 75 73 20 70 61 72 61 67 72 61 70 68 73 2e 0a  ous paragraphs..
36180 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
36190 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  leep(int);../*.*
361a0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
361b0 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48   Of The Folder H
361c0 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79  olding Temporary
361d0 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49   Files.**.** ^(I
361e0 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61  f this global va
361f0 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74  riable is made t
36200 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  o point to a str
36210 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20  ing which is.** 
36220 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f  the name of a fo
36230 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72  lder (a.k.a. dir
36240 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c  ectory), then al
36250 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  l temporary file
36260 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  s.** created by 
36270 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e  SQLite when usin
36280 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71  g a built-in [sq
36290 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d  lite3_vfs | VFS]
362a0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63  .** will be plac
362b0 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63  ed in that direc
362c0 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69  tory.)^  ^If thi
362d0 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73  s variable.** is
362e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
362f0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72   then SQLite per
36300 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66  forms a search f
36310 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  or an appropriat
36320 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  e.** temporary f
36330 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ile directory..*
36340 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  *.** It is not s
36350 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
36360 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
36370 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e  ble in more than
36380 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61   one.** thread a
36390 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73  t a time.  It is
363a0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
363b0 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
363c0 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20   variable.** if 
363d0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
363e0 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
363f0 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d   used at the sam
36400 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61  e time in a sepa
36410 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a  rate.** thread..
36420 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65  ** It is intende
36430 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
36440 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65  able be set once
36450 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70  .** as part of p
36460 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
36470 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65  ation and before
36480 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
36490 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65  rface.** routine
364a0 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  s have been call
364b0 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ed and that this
364c0 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e   variable remain
364d0 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68   unchanged.** th
364e0 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  ereafter..**.** 
364f0 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65  ^The [temp_store
36500 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
36510 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68  a] may modify th
36520 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20  is variable and 
36530 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70  cause.** it to p
36540 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
36550 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
36560 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20  lite3_malloc].  
36570 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a  ^Furthermore,.**
36580 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65   the [temp_store
36590 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
365a0 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65  a] always assume
365b0 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e  s that any strin
365c0 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76  g.** that this v
365d0 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74  ariable points t
365e0 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d  o is held in mem
365f0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
36600 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  m .** [sqlite3_m
36610 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70  alloc] and the p
36620 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70  ragma may attemp
36630 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d  t to free that m
36640 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b  emory.** using [
36650 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a  sqlite3_free]..*
36660 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73  * Hence, if this
36670 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64   variable is mod
36680 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20  ified directly, 
36690 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64  either it should
366a0 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c   be.** made NULL
366b0 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   or made to poin
366c0 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  t to memory obta
366d0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
366e0 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72  e3_malloc].** or
366f0 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66   else the use of
36700 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65   the [temp_store
36710 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
36720 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f  a] should be avo
36730 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  ided..**.** <b>N
36740 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52  ote to Windows R
36750 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62  untime users:</b
36760 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79  >  The temporary
36770 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20   directory must 
36780 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20  be set.** prior 
36790 74 6f 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  to calling [sqli
367a0 74 65 33 5f 6f 70 65 6e 5d 20 6f 72 20 5b 73 71  te3_open] or [sq
367b0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 5d 2e 20  lite3_open_v2]. 
367c0 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69   Otherwise, vari
367d0 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20  ous.** features 
367e0 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65  that require the
367f0 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72   use of temporar
36800 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c  y files may fail
36810 2e 20 20 48 65 72 65 20 69 73 20 61 6e 0a 2a 2a  .  Here is an.**
36820 20 65 78 61 6d 70 6c 65 20 6f 66 20 68 6f 77 20   example of how 
36830 74 6f 20 64 6f 20 74 68 69 73 20 75 73 69 6e 67  to do this using
36840 20 43 2b 2b 20 77 69 74 68 20 74 68 65 20 57 69   C++ with the Wi
36850 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 3a 0a 2a  ndows Runtime:.*
36860 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
36870 3e 3c 70 72 65 3e 0a 2a 2a 20 4c 50 43 57 53 54  ><pre>.** LPCWST
36880 52 20 7a 50 61 74 68 20 3d 20 57 69 6e 64 6f 77  R zPath = Window
36890 73 3a 3a 53 74 6f 72 61 67 65 3a 3a 41 70 70 6c  s::Storage::Appl
368a0 69 63 61 74 69 6f 6e 44 61 74 61 3a 3a 43 75 72  icationData::Cur
368b0 72 65 6e 74 2d 3e 0a 2a 2a 20 26 6e 62 73 70 3b  rent->.** &nbsp;
368c0 20 20 20 20 20 54 65 6d 70 6f 72 61 72 79 46 6f       TemporaryFo
368d0 6c 64 65 72 2d 3e 50 61 74 68 2d 3e 44 61 74 61  lder->Path->Data
368e0 28 29 3b 0a 2a 2a 20 63 68 61 72 20 7a 50 61 74  ();.** char zPat
368f0 68 42 75 66 26 23 39 31 3b 4d 41 58 5f 50 41 54  hBuf&#91;MAX_PAT
36900 48 20 2b 20 31 26 23 39 33 3b 3b 0a 2a 2a 20 6d  H + 1&#93;;.** m
36910 65 6d 73 65 74 28 7a 50 61 74 68 42 75 66 2c 20  emset(zPathBuf, 
36920 30 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42  0, sizeof(zPathB
36930 75 66 29 29 3b 0a 2a 2a 20 57 69 64 65 43 68 61  uf));.** WideCha
36940 72 54 6f 4d 75 6c 74 69 42 79 74 65 28 43 50 5f  rToMultiByte(CP_
36950 55 54 46 38 2c 20 30 2c 20 7a 50 61 74 68 2c 20  UTF8, 0, zPath, 
36960 2d 31 2c 20 7a 50 61 74 68 42 75 66 2c 20 73 69  -1, zPathBuf, si
36970 7a 65 6f 66 28 7a 50 61 74 68 42 75 66 29 2c 0a  zeof(zPathBuf),.
36980 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 20 4e 55  ** &nbsp;     NU
36990 4c 4c 2c 20 4e 55 4c 4c 29 3b 0a 2a 2a 20 73 71  LL, NULL);.** sq
369a0 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
369b0 74 6f 72 79 20 3d 20 73 71 6c 69 74 65 33 5f 6d  tory = sqlite3_m
369c0 70 72 69 6e 74 66 28 22 25 73 22 2c 20 7a 50 61  printf("%s", zPa
369d0 74 68 42 75 66 29 3b 0a 2a 2a 20 3c 2f 70 72 65  thBuf);.** </pre
369e0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
369f0 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  /.SQLITE_EXTERN 
36a00 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65  char *sqlite3_te
36a10 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f  mp_directory;../
36a20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
36a30 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
36a40 72 20 48 6f 6c 64 69 6e 67 20 44 61 74 61 62 61  r Holding Databa
36a50 73 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e  se Files.**.** ^
36a60 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20  (If this global 
36a70 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65  variable is made
36a80 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73   to point to a s
36a90 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a  tring which is.*
36aa0 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * the name of a 
36ab0 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64  folder (a.k.a. d
36ac0 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20  irectory), then 
36ad0 61 6c 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c  all database fil
36ae0 65 73 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20  es.** specified 
36af0 77 69 74 68 20 61 20 72 65 6c 61 74 69 76 65 20  with a relative 
36b00 70 61 74 68 6e 61 6d 65 20 61 6e 64 20 63 72 65  pathname and cre
36b10 61 74 65 64 20 6f 72 20 61 63 63 65 73 73 65 64  ated or accessed
36b20 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 77 68   by.** SQLite wh
36b30 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74  en using a built
36b40 2d 69 6e 20 77 69 6e 64 6f 77 73 20 5b 73 71 6c  -in windows [sql
36b50 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 20  ite3_vfs | VFS] 
36b60 77 69 6c 6c 20 62 65 20 61 73 73 75 6d 65 64 0a  will be assumed.
36b70 2a 2a 20 74 6f 20 62 65 20 72 65 6c 61 74 69 76  ** to be relativ
36b80 65 20 74 6f 20 74 68 61 74 20 64 69 72 65 63 74  e to that direct
36b90 6f 72 79 2e 29 5e 20 5e 49 66 20 74 68 69 73 20  ory.)^ ^If this 
36ba0 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
36bb0 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 74  LL.** pointer, t
36bc0 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
36bd0 65 73 20 74 68 61 74 20 61 6c 6c 20 64 61 74 61  es that all data
36be0 62 61 73 65 20 66 69 6c 65 73 20 73 70 65 63 69  base files speci
36bf0 66 69 65 64 0a 2a 2a 20 77 69 74 68 20 61 20 72  fied.** with a r
36c00 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65  elative pathname
36c10 20 61 72 65 20 72 65 6c 61 74 69 76 65 20 74 6f   are relative to
36c20 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
36c30 65 63 74 6f 72 79 0a 2a 2a 20 66 6f 72 20 74 68  ectory.** for th
36c40 65 20 70 72 6f 63 65 73 73 2e 20 20 4f 6e 6c 79  e process.  Only
36c50 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
36c60 20 6d 61 6b 65 73 20 75 73 65 20 6f 66 20 74 68   makes use of th
36c70 69 73 20 67 6c 6f 62 61 6c 0a 2a 2a 20 76 61 72  is global.** var
36c80 69 61 62 6c 65 3b 20 69 74 20 69 73 20 69 67 6e  iable; it is ign
36c90 6f 72 65 64 20 62 79 20 74 68 65 20 75 6e 69 78  ored by the unix
36ca0 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 6e   VFS..**.** Chan
36cb0 67 69 6e 67 20 74 68 65 20 76 61 6c 75 65 20 6f  ging the value o
36cc0 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
36cd0 77 68 69 6c 65 20 61 20 64 61 74 61 62 61 73 65  while a database
36ce0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 0a 2a   connection is.*
36cf0 2a 20 6f 70 65 6e 20 63 61 6e 20 72 65 73 75 6c  * open can resul
36d00 74 20 69 6e 20 61 20 63 6f 72 72 75 70 74 20 64  t in a corrupt d
36d10 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49  atabase..**.** I
36d20 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
36d30 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
36d40 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e  this variable in
36d50 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a   more than one.*
36d60 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69  * thread at a ti
36d70 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73  me.  It is not s
36d80 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
36d90 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
36da0 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74  ble.** if a [dat
36db0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36dc0 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  ] is being used 
36dd0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
36de0 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a   in a separate.*
36df0 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20  * thread..** It 
36e00 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74  is intended that
36e10 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62   this variable b
36e20 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73  e set once.** as
36e30 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73   part of process
36e40 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
36e50 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53  and before any S
36e60 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
36e70 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65  ** routines have
36e80 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64   been called and
36e90 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
36ea0 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  ble remain uncha
36eb0 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74  nged.** thereaft
36ec0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  er..**.** ^The [
36ed0 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
36ee0 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79  tory pragma] may
36ef0 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
36f00 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a  iable and cause.
36f10 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74  ** it to point t
36f20 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
36f30 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
36f40 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68  malloc].  ^Furth
36f50 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b  ermore,.** the [
36f60 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
36f70 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77  tory pragma] alw
36f80 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74  ays assumes that
36f90 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74   any string.** t
36fa0 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
36fb0 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68  e points to is h
36fc0 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62  eld in memory ob
36fd0 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
36fe0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
36ff0 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20   and the pragma 
37000 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66  may attempt to f
37010 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a  ree that memory.
37020 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
37030 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63  3_free]..** Henc
37040 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61  e, if this varia
37050 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20  ble is modified 
37060 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72  directly, either
37070 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a   it should be.**
37080 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61   made NULL or ma
37090 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  de to point to m
370a0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
370b0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
370c0 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20  loc].** or else 
370d0 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  the use of the [
370e0 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
370f0 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f  tory pragma] sho
37100 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a  uld be avoided..
37110 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  */.SQLITE_EXTERN
37120 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64   char *sqlite3_d
37130 61 74 61 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a  ata_directory;..
37140 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37150 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f  Test For Auto-Co
37160 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59  mmit Mode.** KEY
37170 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d  WORDS: {autocomm
37180 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e  it mode}.**.** ^
37190 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
371a0 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74  autocommit() int
371b0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e  erface returns n
371c0 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65  on-zero or.** ze
371d0 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20  ro if the given 
371e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
371f0 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74  ion is or is not
37200 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d   in autocommit m
37210 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ode,.** respecti
37220 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d  vely.  ^Autocomm
37230 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79  it mode is on by
37240 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75   default..** ^Au
37250 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
37260 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b   disabled by a [
37270 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74  BEGIN] statement
37280 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ..** ^Autocommit
37290 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62   mode is re-enab
372a0 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54  led by a [COMMIT
372b0 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e  ] or [ROLLBACK].
372c0 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69  .**.** If certai
372d0 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72  n kinds of error
372e0 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61  s occur on a sta
372f0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
37300 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a  multi-statement.
37310 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28  ** transaction (
37320 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67  errors including
37330 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20   [SQLITE_FULL], 
37340 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a  [SQLITE_IOERR],.
37350 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
37360 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ], [SQLITE_BUSY]
37370 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e  , and [SQLITE_IN
37380 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74  TERRUPT]) then t
37390 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  he.** transactio
373a0 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65  n might be rolle
373b0 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
373c0 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ally.  The only 
373d0 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f  way to.** find o
373e0 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74  ut whether SQLit
373f0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
37400 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20  rolled back the 
37410 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65  transaction afte
37420 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73  r.** an error is
37430 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e   to use this fun
37440 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ction..**.** If 
37450 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63  another thread c
37460 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63  hanges the autoc
37470 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20  ommit status of 
37480 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
37490 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
374a0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
374b0 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74   running, then t
374c0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
374d0 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
374e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
374f0 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73  get_autocommit(s
37500 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
37510 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
37520 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e  The Database Han
37530 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65  dle Of A Prepare
37540 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d Statement.**.*
37550 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
37560 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61  b_handle interfa
37570 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
37580 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37590 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74  ion] handle.** t
375a0 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61  o which a [prepa
375b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62  red statement] b
375c0 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64  elongs.  ^The [d
375d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
375e0 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  on].** returned 
375f0 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  by sqlite3_db_ha
37600 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65  ndle is the same
37610 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37620 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77  ction].** that w
37630 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
37640 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20  ument.** to the 
37650 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
37660 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20  _v2()] call (or 
37670 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68  its variants) th
37680 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a  at was used to.*
37690 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61  * create the sta
376a0 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69  tement in the fi
376b0 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71  rst place..*/.sq
376c0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64  lite3 *sqlite3_d
376d0 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
376e0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
376f0 43 41 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e  CAPI3REF: Return
37700 20 54 68 65 20 46 69 6c 65 6e 61 6d 65 20 46 6f   The Filename Fo
37710 72 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e  r A Database Con
37720 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  nection.**.** ^T
37730 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 66 69  he sqlite3_db_fi
37740 6c 65 6e 61 6d 65 28 44 2c 4e 29 20 69 6e 74 65  lename(D,N) inte
37750 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
37760 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 69 6c  pointer to a fil
37770 65 6e 61 6d 65 0a 2a 2a 20 61 73 73 6f 63 69 61  ename.** associa
37780 74 65 64 20 77 69 74 68 20 64 61 74 61 62 61 73  ted with databas
37790 65 20 4e 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f  e N of connectio
377a0 6e 20 44 2e 20 20 5e 54 68 65 20 6d 61 69 6e 20  n D.  ^The main 
377b0 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
377c0 20 68 61 73 20 74 68 65 20 6e 61 6d 65 20 22 6d   has the name "m
377d0 61 69 6e 22 2e 20 20 49 66 20 74 68 65 72 65 20  ain".  If there 
377e0 69 73 20 6e 6f 20 61 74 74 61 63 68 65 64 20 64  is no attached d
377f0 61 74 61 62 61 73 65 20 4e 20 6f 6e 20 74 68 65  atabase N on the
37800 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
37810 6e 65 63 74 69 6f 6e 20 44 2c 20 6f 72 20 69 66  nection D, or if
37820 20 64 61 74 61 62 61 73 65 20 4e 20 69 73 20 61   database N is a
37830 20 74 65 6d 70 6f 72 61 72 79 20 6f 72 20 69 6e   temporary or in
37840 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
37850 2c 20 74 68 65 6e 0a 2a 2a 20 61 20 4e 55 4c 4c  , then.** a NULL
37860 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
37870 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
37880 20 66 69 6c 65 6e 61 6d 65 20 72 65 74 75 72 6e   filename return
37890 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74  ed by this funct
378a0 69 6f 6e 20 69 73 20 74 68 65 20 6f 75 74 70 75  ion is the outpu
378b0 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 46 75 6c  t of the.** xFul
378c0 6c 50 61 74 68 6e 61 6d 65 20 6d 65 74 68 6f 64  lPathname method
378d0 20 6f 66 20 74 68 65 20 5b 56 46 53 5d 2e 20 20   of the [VFS].  
378e0 5e 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  ^In other words,
378f0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
37900 20 77 69 6c 6c 20 62 65 20 61 6e 20 61 62 73 6f   will be an abso
37910 6c 75 74 65 20 70 61 74 68 6e 61 6d 65 2c 20 65  lute pathname, e
37920 76 65 6e 20 69 66 20 74 68 65 20 66 69 6c 65 6e  ven if the filen
37930 61 6d 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6f  ame used.** to o
37940 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
37950 20 6f 72 69 67 69 6e 61 6c 6c 79 20 77 61 73 20   originally was 
37960 61 20 55 52 49 20 6f 72 20 72 65 6c 61 74 69 76  a URI or relativ
37970 65 20 70 61 74 68 6e 61 6d 65 2e 0a 2a 2f 0a 63  e pathname..*/.c
37980 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
37990 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 73  e3_db_filename(s
379a0 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73  qlite3 *db, cons
379b0 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29  t char *zDbName)
379c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
379d0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 69 66 20  F: Determine if 
379e0 61 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  a database is re
379f0 61 64 2d 6f 6e 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54  ad-only.**.** ^T
37a00 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 72 65  he sqlite3_db_re
37a10 61 64 6f 6e 6c 79 28 44 2c 4e 29 20 69 6e 74 65  adonly(D,N) inte
37a20 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 31 20  rface returns 1 
37a30 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
37a40 4e 0a 2a 2a 20 6f 66 20 63 6f 6e 6e 65 63 74 69  N.** of connecti
37a50 6f 6e 20 44 20 69 73 20 72 65 61 64 2d 6f 6e 6c  on D is read-onl
37a60 79 2c 20 30 20 69 66 20 69 74 20 69 73 20 72 65  y, 0 if it is re
37a70 61 64 2f 77 72 69 74 65 2c 20 6f 72 20 2d 31 20  ad/write, or -1 
37a80 69 66 20 4e 20 69 73 20 6e 6f 74 0a 2a 2a 20 74  if N is not.** t
37a90 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 64 61 74  he name of a dat
37aa0 61 62 61 73 65 20 6f 6e 20 63 6f 6e 6e 65 63 74  abase on connect
37ab0 69 6f 6e 20 44 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ion D..*/.int sq
37ac0 6c 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c  lite3_db_readonl
37ad0 79 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63  y(sqlite3 *db, c
37ae0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
37af0 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
37b00 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e  3REF: Find the n
37b10 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61  ext prepared sta
37b20 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  tement.**.** ^Th
37b30 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
37b40 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
37b50 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70  o the next [prep
37b60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
37b70 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61  after.** pStmt a
37b80 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
37b90 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
37ba0 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e  nection] pDb.  ^
37bb0 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c  If pStmt is NULL
37bc0 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e  .** then this in
37bd0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
37be0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
37bf0 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20   first prepared 
37c00 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73  statement.** ass
37c10 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
37c20 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
37c30 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e  tion pDb.  ^If n
37c40 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  o prepared state
37c50 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65  ment.** satisfie
37c60 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73  s the conditions
37c70 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
37c80 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c  , it returns NUL
37c90 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61  L..**.** The [da
37ca0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37cb0 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20  n] pointer D in 
37cc0 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
37cd0 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
37ce0 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72  D,S)] must refer
37cf0 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   to an open data
37d00 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
37d10 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63  on and in partic
37d20 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65  ular must not be
37d30 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
37d40 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74  .*/.sqlite3_stmt
37d50 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   *sqlite3_next_s
37d60 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62  tmt(sqlite3 *pDb
37d70 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  , sqlite3_stmt *
37d80 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
37d90 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20  API3REF: Commit 
37da0 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74  And Rollback Not
37db0 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
37dc0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
37dd0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
37de0 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
37df0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
37e00 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
37e10 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
37e20 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63  enever a transac
37e30 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20  tion is [COMMIT 
37e40 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a  | committed]..**
37e50 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73   ^Any callback s
37e60 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
37e70 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
37e80 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a  _commit_hook().*
37e90 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
37ea0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37eb0 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
37ec0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
37ed0 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
37ee0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
37ef0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
37f00 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
37f10 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
37f20 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
37f30 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c  n is [ROLLBACK |
37f40 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a   rolled back]..*
37f50 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  * ^Any callback 
37f60 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
37f70 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
37f80 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
37f90 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
37fa0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
37fb0 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
37fc0 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72  den..** ^The pAr
37fd0 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61  g argument is pa
37fe0 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ssed through to 
37ff0 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
38000 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
38010 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f  k on a commit ho
38020 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  ok function retu
38030 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a  rns non-zero,.**
38040 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74   then the commit
38050 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e   is converted in
38060 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  to a rollback..*
38070 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
38080 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c  3_commit_hook(D,
38090 43 2c 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33  C,P) and sqlite3
380a0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44  _rollback_hook(D
380b0 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a  ,C,P) functions.
380c0 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 50 20  ** return the P 
380d0 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68  argument from th
380e0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
380f0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
38100 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73  tion.** on the s
38110 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
38120 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20  nnection] D, or 
38130 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20  NULL for.** the 
38140 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65  first call for e
38150 61 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20  ach function on 
38160 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6d  D..**.** The com
38170 6d 69 74 20 61 6e 64 20 72 6f 6c 6c 62 61 63 6b  mit and rollback
38180 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 73 20   hook callbacks 
38190 61 72 65 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e  are not reentran
381a0 74 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  t..** The callba
381b0 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ck implementatio
381c0 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  n must not do an
381d0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
381e0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
381f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38200 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
38210 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41  the callback.  A
38220 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f  ny actions.** to
38230 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
38240 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
38250 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64  must be deferred
38260 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
38270 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f  .** completion o
38280 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  f the [sqlite3_s
38290 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74  tep()] call that
382a0 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63   triggered the c
382b0 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c  ommit.** or roll
382c0 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65  back hook in the
382d0 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a   first place..**
382e0 20 4e 6f 74 65 20 74 68 61 74 20 72 75 6e 6e 69   Note that runni
382f0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
38300 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 69 6e 63   statements, inc
38310 6c 75 64 69 6e 67 20 53 45 4c 45 43 54 20 73 74  luding SELECT st
38320 61 74 65 6d 65 6e 74 73 2c 0a 2a 2a 20 6f 72 20  atements,.** or 
38330 6d 65 72 65 6c 79 20 63 61 6c 6c 69 6e 67 20 5b  merely calling [
38340 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
38350 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
38360 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
38370 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
38380 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
38390 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
383a0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
383b0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
383c0 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65  ..**.** ^Registe
383d0 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63  ring a NULL func
383e0 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68  tion disables th
383f0 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  e callback..**.*
38400 2a 20 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d  * ^When the comm
38410 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b  it hook callback
38420 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
38430 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d   zero, the [COMM
38440 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e  IT].** operation
38450 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63   is allowed to c
38460 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79  ontinue normally
38470 2e 20 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69  .  ^If the commi
38480 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e  t hook.** return
38490 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
384a0 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73   the [COMMIT] is
384b0 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
384c0 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a  a [ROLLBACK]..**
384d0 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68   ^The rollback h
384e0 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ook is invoked o
384f0 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61  n a rollback tha
38500 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61  t results from a
38510 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20   commit.** hook 
38520 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65  returning non-ze
38530 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77  ro, just as it w
38540 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79  ould be with any
38550 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e   other rollback.
38560 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
38570 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
38580 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74   API, a transact
38590 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68  ion is said to h
385a0 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c  ave been.** roll
385b0 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78  ed back if an ex
385c0 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b  plicit "ROLLBACK
385d0 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65  " statement is e
385e0 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61  xecuted, or.** a
385f0 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74  n error or const
38600 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20  raint causes an 
38610 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63  implicit rollbac
38620 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e  k to occur..** ^
38630 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c  The rollback cal
38640 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76  lback is not inv
38650 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61  oked if a transa
38660 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f  ction is.** auto
38670 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
38680 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 68   back because th
38690 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
386a0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
386b0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
386c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64  the [sqlite3_upd
386d0 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65  ate_hook()] inte
386e0 72 66 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  rface..*/.void *
386f0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
38700 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ook(sqlite3*, in
38710 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
38720 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  d*);.void *sqlit
38730 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
38740 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
38750 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64  *)(void *), void
38760 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
38770 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65  REF: Data Change
38780 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61   Notification Ca
38790 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
387a0 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74  he sqlite3_updat
387b0 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  e_hook() interfa
387c0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
387d0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
387e0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61  .** with the [da
387f0 74 61 62 61 73 65 20 63 6f 6e 6