/ Hex Artifact Content
Login

Artifact 5f2eedc52ee7e9f8c560faf862cffbb86d81eb44:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69 73  3_close()].** is
23f0: 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e   its destructor.
2400: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
2410: 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   other interface
2420: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73  s (such as.** [s
2430: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2440: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  2()], [sqlite3_c
2450: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2460: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2470: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
2480: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74  )] to name but t
2490: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d  hree) that are m
24a0: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20  ethods on an.** 
24b0: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a  sqlite3 object..
24c0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
24d0: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65  t sqlite3 sqlite
24e0: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  3;../*.** CAPI3R
24f0: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67  EF: 64-Bit Integ
2500: 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57  er Types.** KEYW
2510: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74  ORDS: sqlite_int
2520: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2530: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
2540: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73  here is no cross
2550: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f  -platform way to
2560: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20   specify 64-bit 
2570: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a  integer types.**
2580: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73   SQLite includes
2590: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34   typedefs for 64
25a0: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20  -bit signed and 
25b0: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
25c0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
25d0: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
25e0: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72  qlite3_uint64 ar
25f0: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2600: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  type definitions
2610: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f  ..** The sqlite_
2620: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2630: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72  _uint64 types ar
2640: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20  e supported for 
2650: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d  backwards.** com
2660: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
2670: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2680: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
2690: 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73  lite_int64 types
26a0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
26b0: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  er values.** bet
26c0: 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36  ween -9223372036
26d0: 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39  854775808 and +9
26e0: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
26f0: 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e  07 inclusive.  ^
2700: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  The.** sqlite3_u
2710: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2720: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  _uint64 types ca
2730: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
2740: 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65  values .** betwe
2750: 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37  en 0 and +184467
2760: 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69  44073709551615 i
2770: 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66  nclusive..*/.#if
2780: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
2790: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
27a0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
27b0: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
27c0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
27d0: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
27e0: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
27f0: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
2800: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
2810: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
2820: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
2830: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
2840: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2850: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
2860: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
2870: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
2880: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
2890: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
28a0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
28b0: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
28c0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
28d0: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
28e0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
28f0: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
2900: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
2910: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
2920: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
2930: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
2940: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
2950: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
2960: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
2970: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
2980: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
2990: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
29a0: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
29b0: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
29c0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
29d0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
29e0: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
29f0: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
2a00: 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
2a10: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2a20: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20   routine is the 
2a30: 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
2a40: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
2a50: 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ect..** ^Calls t
2a60: 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  o sqlite3_close(
2a70: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
2a80: 4f 4b 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  OK if the [sqlit
2a90: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  e3] object is.**
2aa0: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65   successfully de
2ab0: 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20  stroyed and all 
2ac0: 61 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f 75  associated resou
2ad0: 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63  rces are dealloc
2ae0: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ated..**.** Appl
2af0: 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b 73  ications must [s
2b00: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
2b10: 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20  | finalize] all 
2b20: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b30: 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  ents].** and [sq
2b40: 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
2b50: 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42   | close] all [B
2b60: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 73  LOB handles] ass
2b70: 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20  ociated with.** 
2b80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2b90: 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74  ject prior to at
2ba0: 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73  tempting to clos
2bb0: 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e  e the object.  ^
2bc0: 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c  If.** sqlite3_cl
2bd0: 6f 73 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ose() is called 
2be0: 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  on a [database c
2bf0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20  onnection] that 
2c00: 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74  still has.** out
2c10: 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72  standing [prepar
2c20: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 6f  ed statements] o
2c30: 72 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  r [BLOB handles]
2c40: 2c 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e  , then it return
2c50: 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59  s.** SQLITE_BUSY
2c60: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71 6c  ..**.** ^If [sql
2c70: 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73  ite3_close()] is
2c80: 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61   invoked while a
2c90: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
2ca0: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61  open,.** the tra
2cb0: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f  nsaction is auto
2cc0: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
2cd0: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   back..**.** The
2ce0: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   C parameter to 
2cf0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
2d00: 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  )] must be eithe
2d10: 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
2d20: 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74  ter or an [sqlit
2d30: 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74  e3] object point
2d40: 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  er obtained.** f
2d50: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  rom [sqlite3_ope
2d60: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
2d70: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  pen16()], or.** 
2d80: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
2d90: 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65  ()], and not pre
2da0: 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a  viously closed..
2db0: 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
2dc0: 74 65 33 5f 63 6c 6f 73 65 28 29 20 77 69 74 68  te3_close() with
2dd0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2de0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 0a 2a  argument is a .*
2df0: 2a 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  * harmless no-op
2e00: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2e10: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a  _close(sqlite3 *
2e20: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
2e30: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
2e40: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
2e50: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
2e60: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
2e70: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
2e80: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
2e90: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
2ea0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
2eb0: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
2ec0: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
2ed0: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
2ee0: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
2ef0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f00: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
2f10: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
2f20: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65  erface.**.** The
2f30: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
2f40: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
2f50: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
2f60: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
2f70: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2f80: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
2f90: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
2fa0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
2fb0: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
2fc0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
2fd0: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
2fe0: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
2ff0: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
3000: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
3010: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
3020: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
3030: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
3040: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
3050: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
3060: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
3070: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
3080: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
3090: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
30a0: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
30b0: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
30c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30d0: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
30e0: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
30f0: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
3100: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3110: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
3120: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
3130: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3140: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
3150: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
3160: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
3170: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
3180: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
3190: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
31a0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
31b0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
31c0: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74  c() is relayed t
31d0: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73  hrough to the 1s
31e0: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61  t argument of ea
31f0: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ch.** callback i
3200: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20  nvocation.  ^If 
3210: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69  the callback poi
3220: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
3230: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c  exec().** is NUL
3240: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62  L, then no callb
3250: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f  ack is ever invo
3260: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72  ked and result r
3270: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72  ows are.** ignor
3280: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3290: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
32a0: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74  ile evaluating t
32b0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
32c0: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  s passed into.**
32d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
32e0: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20   then execution 
32f0: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  of the current s
3300: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61  tatement stops a
3310: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  nd.** subsequent
3320: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
3330: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68  skipped.  ^If th
3340: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3350: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3360: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ).** is not NULL
3370: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20   then any error 
3380: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74  message is writt
3390: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
33a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
33b0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
33c0: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61  )] and passed ba
33d0: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ck through the 5
33e0: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  th parameter..**
33f0: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79   To avoid memory
3400: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c   leaks, the appl
3410: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69  ication should i
3420: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
3430: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72  ree()].** on err
3440: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
3450: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  gs returned thro
3460: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3470: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73  meter of.** of s
3480: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3490: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
34a0: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
34b0: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
34c0: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
34d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
34e0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
34f0: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3500: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3510: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3520: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3530: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3540: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3550: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3560: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3570: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3580: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3590: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
35a0: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
35b0: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
35c0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
35d0: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
35e0: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
35f0: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3600: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3610: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3620: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3630: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3640: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3650: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3660: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3670: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3680: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3690: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
36a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
36b0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
36c0: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
36d0: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
36e0: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
36f0: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3700: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3710: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3720: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3730: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3740: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3750: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3760: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3770: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3780: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3790: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
37a0: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
37b0: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
37c0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
37d0: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
37e0: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
37f0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3800: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3810: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3820: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3830: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3840: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3850: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
3860: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3870: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
3880: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
3890: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
38a0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
38b0: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
38c0: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
38d0: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
38e0: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
38f0: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
3900: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
3910: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
3920: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
3930: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
3940: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
3950: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
3960: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
3970: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
3980: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
3990: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
39a0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
39b0: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68  t insure that th
39c0: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
39d0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
39e0: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
39f0: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
3a00: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3a10: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
3a20: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3a30: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74  t not close [dat
3a40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a50: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  ] specified by.*
3a60: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70  *      the 1st p
3a70: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3a80: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
3a90: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3aa0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
3ab0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
3ac0: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64  ion must not mod
3ad0: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74  ify the SQL stat
3ae0: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65  ement text passe
3af0: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74  d into.**      t
3b00: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
3b10: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
3b20: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
3b30: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
3b40: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ng..** </ul>.*/.
3b50: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
3b60: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3b90: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
3ba0: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
3bb0: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
3be0: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69  evaluated */.  i
3bf0: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
3c00: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
3c10: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
3c20: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
3c30: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3c60: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
3c70: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
3c80: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **errmsg   
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
3cb0: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
3cc0: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
3cd0: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
3ce0: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
3cf0: 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20  ORDS: SQLITE_OK 
3d00: 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72  {error code} {er
3d10: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
3d20: 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20  YWORDS: {result 
3d30: 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f  code} {result co
3d40: 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  des}.**.** Many 
3d50: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
3d60: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
3d70: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
3d80: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
3d90: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64  n.** here in ord
3da0: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73  er to indicate s
3db0: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
3dc0: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
3dd0: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
3de0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
3df0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
3e00: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
3e10: 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  so: [SQLITE_IOER
3e20: 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
3e30: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c  d result codes],
3e40: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  .** [sqlite3_vta
3e50: 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
3e60: 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43   [SQLITE_ROLLBAC
3e70: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
3e80: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
3e90: 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20  LITE_OK         
3ea0: 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73    0   /* Success
3eb0: 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a  ful result */./*
3ec0: 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72   beginning-of-er
3ed0: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65  ror-codes */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f  fine SQLITE_ERRO
3ef0: 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20  R        1   /* 
3f00: 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73  SQL error or mis
3f10: 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f  sing database */
3f20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f30: 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20  INTERNAL     2  
3f40: 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67   /* Internal log
3f50: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69  ic error in SQLi
3f60: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
3f70: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20  LITE_PERM       
3f80: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20    3   /* Access 
3f90: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65  permission denie
3fa0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
3fb0: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20  ITE_ABORT       
3fc0: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b   4   /* Callback
3fd0: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74   routine request
3fe0: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23  ed an abort */.#
3ff0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
4000: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f  SY         5   /
4010: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66  * The database f
4020: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ile is locked */
4030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4040: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20  LOCKED       6  
4050: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74   /* A table in t
4060: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c  he database is l
4070: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
4080: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20   SQLITE_NOMEM   
4090: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61       7   /* A ma
40a0: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f  lloc() failed */
40b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
40c0: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20  READONLY     8  
40d0: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77   /* Attempt to w
40e0: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20  rite a readonly 
40f0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
4100: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
4110: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f  RUPT    9   /* O
4120: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61  peration termina
4130: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
4140: 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65  nterrupt()*/.#de
4150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4160: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20  R       10   /* 
4170: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73  Some kind of dis
4180: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75  k I/O error occu
4190: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rred */.#define 
41a0: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20  SQLITE_CORRUPT  
41b0: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64     11   /* The d
41c0: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61  atabase disk ima
41d0: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20  ge is malformed 
41e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
41f0: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32  E_NOTFOUND    12
4200: 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70     /* Unknown op
4210: 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f  code in sqlite3_
4220: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a  file_control() *
4230: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4240: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20  _FULL        13 
4250: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66    /* Insertion f
4260: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61  ailed because da
4270: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a  tabase is full *
4280: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4290: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20  _CANTOPEN    14 
42a0: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f    /* Unable to o
42b0: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
42c0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
42d0: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c   SQLITE_PROTOCOL
42e0: 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61      15   /* Data
42f0: 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63  base lock protoc
4300: 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  ol error */.#def
4310: 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59  ine SQLITE_EMPTY
4320: 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44         16   /* D
4330: 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79  atabase is empty
4340: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4350: 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31  TE_SCHEMA      1
4360: 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  7   /* The datab
4370: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
4380: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4390: 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20  LITE_TOOBIG     
43a0: 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20   18   /* String 
43b0: 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20  or BLOB exceeds 
43c0: 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64  size limit */.#d
43d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
43e0: 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a  STRAINT  19   /*
43f0: 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f   Abort due to co
4400: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
4410: 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  on */.#define SQ
4420: 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20  LITE_MISMATCH   
4430: 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79   20   /* Data ty
4440: 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23  pe mismatch */.#
4450: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
4460: 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f  SUSE      21   /
4470: 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69  * Library used i
4480: 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64  ncorrectly */.#d
4490: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c  efine SQLITE_NOL
44a0: 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a  FS       22   /*
44b0: 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65   Uses OS feature
44c0: 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20  s not supported 
44d0: 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69  on host */.#defi
44e0: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20  ne SQLITE_AUTH  
44f0: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75        23   /* Au
4500: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69  thorization deni
4510: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4520: 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20  LITE_FORMAT     
4530: 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61   24   /* Auxilia
4540: 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d  ry database form
4550: 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  at error */.#def
4560: 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45  ine SQLITE_RANGE
4570: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32         25   /* 2
4580: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
4590: 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74  sqlite3_bind out
45a0: 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65   of range */.#de
45b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41  fine SQLITE_NOTA
45c0: 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20  DB      26   /* 
45d0: 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74  File opened that
45e0: 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
45f0: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4600: 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20  ne SQLITE_ROW   
4610: 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71        100  /* sq
4620: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4630: 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61   another row rea
4640: 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  dy */.#define SQ
4650: 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20  LITE_DONE       
4660: 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33   101  /* sqlite3
4670: 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69  _step() has fini
4680: 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a  shed executing *
4690: 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f  /./* end-of-erro
46a0: 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a  r-codes */../*.*
46b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65  * CAPI3REF: Exte
46c0: 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
46d0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
46e0: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
46f0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65  ode} {extended e
4700: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
4710: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
4720: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  ed result code} 
4730: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
4740: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e   codes}.**.** In
4750: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
4760: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
4770: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
4780: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
4790: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
47a0: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
47b0: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
47c0: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
47d0: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
47e0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
47f0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
4800: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
4810: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
4820: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
4830: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
4840: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
4850: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
4860: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
4870: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
4880: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
4890: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
48a0: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
48b0: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
48c0: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
48d0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
48e0: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
48f0: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
4900: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
4910: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
4920: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  rs. The extended
4930: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4940: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
4950: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
4960: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
4970: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
4980: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
4990: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
49a0: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a  t_codes()] API..
49b0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
49c0: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65  e available exte
49d0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
49e0: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72  s are listed her
49f0: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78  e..** One may ex
4a00: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
4a10: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
4a20: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
4a30: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
4a40: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
4a50: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
4a60: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4a70: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
4a80: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
4a90: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
4aa0: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
4ab0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
4ac0: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c   SQLITE_OK resul
4ad0: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65  t code will neve
4ae0: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20  r be extended.  
4af0: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a  It will always.*
4b00: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72  * be exactly zer
4b10: 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  o..*/.#define SQ
4b20: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
4b30: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4b40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
4b50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4b60: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
4b70: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c  READ        (SQL
4b80: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c  ITE_IOERR | (2<<
4b90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ba0: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20  TE_IOERR_WRITE  
4bb0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4bc0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
4bd0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4be0: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
4bf0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4c00: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
4c10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4c20: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
4c30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4c40: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
4c50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c60: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
4c70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4c80: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a  IOERR | (6<<8)).
4c90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4ca0: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20  OERR_FSTAT      
4cb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4cc0: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
4cd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ce0: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
4cf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4d00: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
4d10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d20: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
4d30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d40: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
4d50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4d60: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
4d70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4d80: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65  R | (10<<8)).#de
4d90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4da0: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  R_BLOCKED       
4db0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4dc0: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
4dd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4de0: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
4df0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4e00: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65  R | (12<<8)).#de
4e10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e20: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20  R_ACCESS        
4e30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4e40: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65  R | (13<<8)).#de
4e50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e60: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c  R_CHECKRESERVEDL
4e70: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52  OCK (SQLITE_IOER
4e80: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65  R | (14<<8)).#de
4e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ea0: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  R_LOCK          
4eb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4ec0: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65  R | (15<<8)).#de
4ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ee0: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
4ef0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f00: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65  R | (16<<8)).#de
4f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f20: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20  R_DIR_CLOSE     
4f30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f40: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65  R | (17<<8)).#de
4f50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f60: 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20  R_SHMOPEN       
4f70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f80: 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65  R | (18<<8)).#de
4f90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4fa0: 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20  R_SHMSIZE       
4fb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4fc0: 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65  R | (19<<8)).#de
4fd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4fe0: 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20  R_SHMLOCK       
4ff0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5000: 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65  R | (20<<8)).#de
5010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5020: 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20  R_SHMMAP        
5030: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5040: 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65  R | (21<<8)).#de
5050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5060: 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20  R_SEEK          
5070: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5080: 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65  R | (22<<8)).#de
5090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
50a0: 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  ED_SHAREDCACHE  
50b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
50c0: 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64  ED |  (1<<8)).#d
50d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
50e0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
50f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5100: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  Y   |  (1<<8)).#
5110: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5120: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5130: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5140: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5160: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
5170: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5180: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5190: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
51a0: 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20  E_CORRUPT_VTAB  
51b0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
51c0: 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c  E_CORRUPT | (1<<
51d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
51e0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f  TE_READONLY_RECO
51f0: 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c 49  VERY       (SQLI
5200: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31  TE_READONLY | (1
5210: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5220: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41  LITE_READONLY_CA
5230: 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51  NTLOCK       (SQ
5240: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
5250: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5260: 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c  SQLITE_ABORT_ROL
5270: 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28  LBACK          (
5280: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28  SQLITE_ABORT | (
5290: 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  2<<8))../*.** CA
52a0: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f  PI3REF: Flags Fo
52b0: 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72  r File Open Oper
52c0: 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ations.**.** The
52d0: 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72  se bit values ar
52e0: 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
52f0: 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64  se in the.** 3rd
5300: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5310: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  e [sqlite3_open_
5320: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
5330: 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74  and.** in the 4t
5340: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
5350: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
5360: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a  xOpen] method..*
5370: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5380: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20  _OPEN_READONLY  
5390: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
53a0: 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  1  /* Ok for sql
53b0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
53c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
53d0: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
53e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
53f0: 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  2  /* Ok for sql
5400: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5410: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5420: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20  _OPEN_CREATE    
5430: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5440: 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  4  /* Ok for sql
5450: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5460: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5470: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
5480: 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30  OSE    0x0000000
5490: 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  8  /* VFS only *
54a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
54b0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
54c0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
54d0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
54e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
54f0: 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20  _OPEN_AUTOPROXY 
5500: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
5510: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5520: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5530: 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20  _OPEN_URI       
5540: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
5550: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
5560: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5570: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5580: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20  _OPEN_MAIN_DB   
5590: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
55a0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
55b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
55c0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20  _OPEN_TEMP_DB   
55d0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
55e0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
55f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5600: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
5610: 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30  DB     0x0000040
5620: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5630: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5640: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
5650: 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30  AL     0x0000080
5660: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5670: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5680: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
5690: 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30  AL     0x0000100
56a0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
56b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
56c0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
56d0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
56e0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
56f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5700: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
5710: 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30  RNAL   0x0000400
5720: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5730: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5740: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20  _OPEN_NOMUTEX   
5750: 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30         0x0000800
5760: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
5770: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5780: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5790: 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20  _OPEN_FULLMUTEX 
57a0: 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30         0x0001000
57b0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
57c0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
57d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
57e0: 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
57f0: 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30  E      0x0002000
5800: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
5810: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5820: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5830: 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
5840: 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30  HE     0x0004000
5850: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
5860: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5870: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5880: 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20  _OPEN_WAL       
5890: 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30         0x0008000
58a0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
58b0: 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20  /../* Reserved: 
58c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
58d0: 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30          0x00F000
58e0: 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00 */../*.** CAP
58f0: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
5900: 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a  aracteristics.**
5910: 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43  .** The xDeviceC
5920: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
5930: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71  ethod of the [sq
5940: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
5950: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75  ].** object retu
5960: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77  rns an integer w
5970: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72  hich is a vector
5980: 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a   of the these.**
5990: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72   bit values expr
59a0: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61  essing I/O chara
59b0: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68  cteristics of th
59c0: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a  e mass storage.*
59d0: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f  * device that ho
59e0: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61  lds the file tha
59f0: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  t the [sqlite3_i
5a00: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65  o_methods].** re
5a10: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54  fers to..**.** T
5a20: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
5a30: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
5a40: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
5a50: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
5a60: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
5a70: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
5a80: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
5a90: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
5aa0: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
5ab0: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
5ac0: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
5ad0: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
5ae0: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
5af0: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
5b00: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
5b10: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
5b20: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
5b30: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
5b40: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
5b50: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
5b60: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
5b70: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
5b80: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
5b90: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
5ba0: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
5bb0: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
5bc0: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
5bd0: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
5be0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
5bf0: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
5c00: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
5c10: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
5c20: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
5c30: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
5c40: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
5c50: 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54  te().  The SQLIT
5c60: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
5c70: 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70  E_OVERWRITE prop
5c80: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
5c90: 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20  ** after reboot 
5ca0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73  following a cras
5cb0: 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c  h or power loss,
5cc0: 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20   the only bytes 
5cd0: 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61  in a.** file tha
5ce0: 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61  t were written a
5cf0: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
5d00: 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61  n level might ha
5d10: 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e  ve changed.** an
5d20: 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20  d that adjacent 
5d30: 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65  bytes, even byte
5d40: 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  s within the sam
5d50: 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20  e sector are.** 
5d60: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
5d70: 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23   unchanged..*/.#
5d80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5d90: 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  CAP_ATOMIC      
5da0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5db0: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
5dc0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5dd0: 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20  C512            
5de0: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
5df0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5e00: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20  P_ATOMIC1K      
5e10: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5e20: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
5e30: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
5e40: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
5e50: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
5e60: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5e70: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
5e80: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
5e90: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5ea0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20  _IOCAP_ATOMIC8K 
5eb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5ec0: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65  00000020.#define
5ed0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5ee0: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20  OMIC16K         
5ef0: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a       0x00000040.
5f00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5f10: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20  OCAP_ATOMIC32K  
5f20: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5f30: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
5f40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5f50: 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20  IC64K           
5f60: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
5f70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5f80: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20  AP_SAFE_APPEND  
5f90: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5fa0: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
5fb0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
5fc0: 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  TIAL            
5fd0: 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66   0x00000400.#def
5fe0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5ff0: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
6000: 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38  N_OPEN  0x000008
6010: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6020: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
6030: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30  E_OVERWRITE    0
6040: 78 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a  x00001000../*.**
6050: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20   CAPI3REF: File 
6060: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a  Locking Levels.*
6070: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
6080: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
6090: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
60a0: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  the second.** ar
60b0: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20  gument to calls 
60c0: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20  it makes to the 
60d0: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
60e0: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a  ock() methods.**
60f0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
6100: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6110: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
6120: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20  QLITE_LOCK_NONE 
6130: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
6140: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  ne SQLITE_LOCK_S
6150: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23  HARED        1.#
6160: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6170: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20  CK_RESERVED     
6180: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
6190: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20  E_LOCK_PENDING  
61a0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
61b0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
61c0: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a  SIVE     4../*.*
61d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63  * CAPI3REF: Sync
61e0: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65  hronization Type
61f0: 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65   Flags.**.** Whe
6200: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
6210: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74   the xSync() met
6220: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71  hod of an.** [sq
6230: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6240: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73  ] object it uses
6250: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
6260: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67  f.** these integ
6270: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6280: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
6290: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
62a0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
62b0: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73  AONLY flag is us
62c0: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  ed, it means tha
62d0: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70  t the.** sync op
62e0: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65  eration only nee
62f0: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  ds to flush data
6300: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65   to mass storage
6310: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f  .  Inode.** info
6320: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74  rmation need not
6330: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20   be flushed. If 
6340: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
6350: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a  its of the flag.
6360: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ** equal SQLITE_
6370: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61  SYNC_NORMAL, tha
6380: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e  t means to use n
6390: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65  ormal fsync() se
63a0: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74  mantics..** If t
63b0: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
63c0: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ts equal SQLITE_
63d0: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20  SYNC_FULL, that 
63e0: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
63f0: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
6400: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
6410: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a  of fsync()..**.*
6420: 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65  * Do not confuse
6430: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
6440: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
6450: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
6460: 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  gs.** with the [
6470: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
6480: 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b  us]=NORMAL and [
6490: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
64a0: 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74  us]=FULL.** sett
64b0: 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63  ings.  The [sync
64c0: 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20  hronous pragma] 
64d0: 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20  determines when 
64e0: 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20  calls to the.** 
64f0: 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64  xSync VFS method
6500: 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69   occur and appli
6510: 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72  es uniformly acr
6520: 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d  oss all platform
6530: 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  s..** The SQLITE
6540: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
6550: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6560: 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e  L flags determin
6570: 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74  e how.** energet
6580: 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f  ic or rigorous o
6590: 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73  r forceful the s
65a0: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ync operations a
65b0: 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d  re and.** only m
65c0: 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65  ake a difference
65d0: 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20   on Mac OSX for 
65e0: 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69  the default SQLi
65f0: 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69  te code..** (Thi
6600: 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70  rd-party VFS imp
6610: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67  lementations mig
6620: 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65  ht also make the
6630: 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20   distinction.** 
6640: 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53  between SQLITE_S
6650: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
6660: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
6670: 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a   but among the.*
6680: 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  * operating syst
6690: 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70  ems natively sup
66a0: 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
66b0: 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a  , only Mac OSX.*
66c0: 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68  * cares about th
66d0: 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a  e difference.).*
66e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
66f0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20  _SYNC_NORMAL    
6700: 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66      0x00002.#def
6710: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
6720: 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78  FULL          0x
6730: 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51  00003.#define SQ
6740: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
6750: 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a  LY      0x00010.
6760: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6770: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70   OS Interface Op
6780: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a  en File Handle.*
6790: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
67a0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
67b0: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
67c0: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a   file in the .**
67d0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
67e0: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
67f0: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  er].  Individual
6800: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a   OS interface.**
6810: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
6820: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f   will.** want to
6830: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f   subclass this o
6840: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69  bject by appendi
6850: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  ng additional fi
6860: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69  elds.** for thei
6870: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20  r own use.  The 
6880: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69  pMethods entry i
6890: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
68a0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
68b0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
68c0: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65   that defines me
68d0: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72  thods for perfor
68e0: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72  ming.** I/O oper
68f0: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70  ations on the op
6900: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65  en file..*/.type
6910: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
6920: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f  e3_file sqlite3_
6930: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c  file;.struct sql
6940: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f  ite3_file {.  co
6950: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
6960: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70  e3_io_methods *p
6970: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74  Methods;  /* Met
6980: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e  hods for an open
6990: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a   file */.};../*.
69a0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
69b0: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56  Interface File V
69c0: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f  irtual Methods O
69d0: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72  bject.**.** Ever
69e0: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79  y file opened by
69f0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
6a00: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
6a10: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20  populates an.** 
6a20: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
6a30: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20  bject (or, more 
6a40: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63  commonly, a subc
6a50: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  lass of the.** [
6a60: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
6a70: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69  ject) with a poi
6a80: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
6a90: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
6aa0: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  ct..** This obje
6ab0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d  ct defines the m
6ac0: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70  ethods used to p
6ad0: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f  erform various o
6ae0: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61  perations.** aga
6af0: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69  inst the open fi
6b00: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  le represented b
6b10: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  y the [sqlite3_f
6b20: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  ile] object..**.
6b30: 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74  ** If the [sqlit
6b40: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
6b50: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
6b60: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
6b70: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
6b80: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
6b90: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
6ba0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6bb0: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
6bc0: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
6bd0: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b  ed even if the [
6be0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
6bf0: 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74  n] reported that
6c00: 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65   it failed.  The
6c10: 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20  .** only way to 
6c20: 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74  prevent a call t
6c30: 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69  o xClose followi
6c40: 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c  ng a failed [sql
6c50: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a  ite3_vfs.xOpen].
6c60: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73  ** is for the [s
6c70: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
6c80: 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c  ] to set the sql
6c90: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
6ca0: 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f  ds element.** to
6cb0: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
6cc0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
6cd0: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20  to xSync may be 
6ce0: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53  one of [SQLITE_S
6cf0: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a  YNC_NORMAL] or.*
6d00: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  * [SQLITE_SYNC_F
6d10: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ULL].  The first
6d20: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e   choice is the n
6d30: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a  ormal fsync()..*
6d40: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f  * The second cho
6d50: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20  ice is a Mac OS 
6d60: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
6d70: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53  .  The [SQLITE_S
6d80: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a  YNC_DATAONLY].**
6d90: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65   flag may be ORe
6da0: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  d in to indicate
6db0: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
6dc0: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a  ata of the file.
6dd0: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69  ** and not its i
6de0: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65  node needs to be
6df0: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   synced..**.** T
6e00: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  he integer value
6e10: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64  s to xLock() and
6e20: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f   xUnlock() are o
6e30: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ne of.** <ul>.**
6e40: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
6e50: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69  CK_NONE],.** <li
6e60: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  > [SQLITE_LOCK_S
6e70: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  HARED],.** <li> 
6e80: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
6e90: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  ERVED],.** <li> 
6ea0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
6eb0: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  DING], or.** <li
6ec0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  > [SQLITE_LOCK_E
6ed0: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f  XCLUSIVE]..** </
6ee0: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69  ul>.** xLock() i
6ef0: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ncreases the loc
6f00: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63  k. xUnlock() dec
6f10: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
6f20: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65  .** The xCheckRe
6f30: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74  servedLock() met
6f40: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68  hod checks wheth
6f50: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  er any database 
6f60: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65  connection,.** e
6f70: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72  ither in this pr
6f80: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
6f90: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
6fa0: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53  is holding a RES
6fb0: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
6fc0: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
6fd0: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
6fe0: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
6ff0: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
7000: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
7010: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e  false otherwise.
7020: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65  .**.** The xFile
7030: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64  Control() method
7040: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e   is a generic in
7050: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c  terface that all
7060: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46  ows custom.** VF
7070: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7080: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f  s to directly co
7090: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69  ntrol an open fi
70a0: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
70b0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
70c0: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
70d0: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ce.  The second 
70e0: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73  "op" argument is
70f0: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f   an.** integer o
7100: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72  pcode.  The thir
7110: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
7120: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
7130: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70  intended to.** p
7140: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74  oint to a struct
7150: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e  ure that may con
7160: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f  tain arguments o
7170: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68  r space in which
7180: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74   to.** write ret
7190: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74  urn values.  Pot
71a0: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20  ential uses for 
71b0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
71c0: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74  ight be.** funct
71d0: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62  ions to enable b
71e0: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69  locking locks wi
71f0: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20  th timeouts, to 
7200: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f  change the.** lo
7210: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28  cking strategy (
7220: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75  for example to u
7230: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b  se dot-file lock
7240: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a  s), to inquire.*
7250: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74  * about the stat
7260: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72  us of a lock, or
7270: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20   to break stale 
7280: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69  locks.  The SQLi
7290: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72  te.** core reser
72a0: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20  ves all opcodes 
72b0: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f  less than 100 fo
72c0: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a  r its own use..*
72d0: 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  * A [SQLITE_FCNT
72e0: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69  L_LOCKSTATE | li
72f0: 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c  st of opcodes] l
7300: 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20  ess than 100 is 
7310: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70  available..** Ap
7320: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
7330: 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20  define a custom 
7340: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
7350: 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f  hod should use o
7360: 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65  pcodes.** greate
7370: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76  r than 100 to av
7380: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20  oid conflicts.  
7390: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
73a0: 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ons should.** re
73b0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  turn [SQLITE_NOT
73c0: 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20  FOUND] for file 
73d0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20  control opcodes 
73e0: 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
73f0: 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a  .** recognize..*
7400: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72  *.** The xSector
7410: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65  Size() method re
7420: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72  turns the sector
7430: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20   size of the.** 
7440: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65  device that unde
7450: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20  rlies the file. 
7460: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   The sector size
7470: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d   is the.** minim
7480: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61  um write that ca
7490: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77  n be performed w
74a0: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e  ithout disturbin
74b0: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73  g.** other bytes
74c0: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54   in the file.  T
74d0: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
74e0: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d  teristics().** m
74f0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
7500: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72  bit vector descr
7510: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20  ibing behaviors 
7520: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  of the.** underl
7530: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a  ying device:.**.
7540: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
7550: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7560: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OMIC].** <li> [S
7570: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7580: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC512].** <li> [
7590: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
75a0: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC1K].** <li> [
75b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
75c0: 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC2K].** <li> [
75d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
75e0: 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC4K].** <li> [
75f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7600: 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC8K].** <li> [
7610: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7620: 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC16K].** <li> 
7630: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7640: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC32K].** <li>
7650: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7660: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC64K].** <li
7670: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7680: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20  SAFE_APPEND].** 
7690: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
76a0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a  AP_SEQUENTIAL].*
76b0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
76c0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
76d0: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
76e0: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
76f0: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
7700: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
7710: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
7720: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
7730: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
7740: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
7750: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
7760: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
7770: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
7780: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
7790: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
77a0: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
77b0: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
77c0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
77d0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
77e0: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
77f0: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
7800: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
7810: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
7820: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
7830: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
7840: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
7850: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
7860: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
7870: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
7880: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
7890: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
78a0: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
78b0: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
78c0: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
78d0: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
78e0: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
78f0: 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52  e()..**.** If xR
7900: 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51  ead() returns SQ
7910: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
7920: 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c  _READ it must al
7930: 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68  so fill.** in th
7940: 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e  e unread portion
7950: 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  s of the buffer 
7960: 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56  with zeros.  A V
7970: 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73  FS that.** fails
7980: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
7990: 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20  ort reads might 
79a0: 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48  seem to work.  H
79b0: 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75  owever,.** failu
79c0: 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  re to zero-fill 
79d0: 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c  short reads will
79e0: 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64   eventually lead
79f0: 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20   to.** database 
7a00: 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74  corruption..*/.t
7a10: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
7a20: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7a30: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
7a40: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
7a50: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b  te3_io_methods {
7a60: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
7a70: 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29  .  int (*xClose)
7a80: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
7a90: 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28  .  int (*xRead)(
7aa0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76  sqlite3_file*, v
7ab0: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20  oid*, int iAmt, 
7ac0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
7ad0: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57  fst);.  int (*xW
7ae0: 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  rite)(sqlite3_fi
7af0: 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  le*, const void*
7b00: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
7b10: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
7b20: 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63  ;.  int (*xTrunc
7b30: 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ate)(sqlite3_fil
7b40: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
7b50: 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  4 size);.  int (
7b60: 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xSync)(sqlite3_
7b70: 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73  file*, int flags
7b80: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
7b90: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
7ba0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
7bb0: 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e  64 *pSize);.  in
7bc0: 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74  t (*xLock)(sqlit
7bd0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
7be0: 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29    int (*xUnlock)
7bf0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7c00: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  int);.  int (*xC
7c10: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
7c20: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7c30: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
7c40: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e    int (*xFileCon
7c50: 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69  trol)(sqlite3_fi
7c60: 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69  le*, int op, voi
7c70: 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20  d *pArg);.  int 
7c80: 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73  (*xSectorSize)(s
7c90: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
7ca0: 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68   int (*xDeviceCh
7cb0: 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73  aracteristics)(s
7cc0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
7cd0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
7ce0: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
7cf0: 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69  version 1 */.  i
7d00: 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71  nt (*xShmMap)(sq
7d10: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7d20: 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20   iPg, int pgsz, 
7d30: 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69  int, void volati
7d40: 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  le**);.  int (*x
7d50: 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  ShmLock)(sqlite3
7d60: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73  _file*, int offs
7d70: 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66  et, int n, int f
7d80: 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a  lags);.  void (*
7d90: 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c  xShmBarrier)(sql
7da0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
7db0: 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28  nt (*xShmUnmap)(
7dc0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7dd0: 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a  nt deleteFlag);.
7de0: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
7df0: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
7e00: 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20   version 2 */.  
7e10: 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65  /* Additional me
7e20: 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64  thods may be add
7e30: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
7e40: 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  eases */.};../*.
7e50: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61  ** CAPI3REF: Sta
7e60: 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72  ndard File Contr
7e70: 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a  ol Opcodes.**.**
7e80: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
7e90: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63  onstants are opc
7ea0: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69  odes for the xFi
7eb0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
7ec0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
7ed0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
7ee0: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74  object and for t
7ef0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
7f00: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
7f10: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
7f20: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
7f30: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63  L_LOCKSTATE] opc
7f40: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
7f50: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
7f60: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
7f70: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
7f80: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69  ol method to wri
7f90: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  te the current s
7fa0: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c  tate of.** the l
7fb0: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c  ock (one of [SQL
7fc0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20  ITE_LOCK_NONE], 
7fd0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
7fe0: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  RED],.** [SQLITE
7ff0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
8000: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
8010: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49  NDING], or [SQLI
8020: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
8030: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69  E]).** into an i
8040: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20  nteger that the 
8050: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f  pArg argument po
8060: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61  ints to. This ca
8070: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75  pability.** is u
8080: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
8090: 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ng and only need
80a0: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
80b0: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
80c0: 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64  ST.** is defined
80d0: 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  ..** <ul>.** <li
80e0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
80f0: 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54  SIZE_HINT]].** T
8100: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8110: 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f  _SIZE_HINT] opco
8120: 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51  de is used by SQ
8130: 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65  Lite to give the
8140: 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20   VFS.** layer a 
8150: 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67  hint of how larg
8160: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
8170: 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f  ile will grow to
8180: 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a   be during the.*
8190: 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  * current transa
81a0: 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e  ction.  This hin
81b0: 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  t is not guarant
81c0: 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61  eed to be accura
81d0: 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20  te but it.** is 
81e0: 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68  often close.  Th
81f0: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53  e underlying VFS
8200: 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f   might choose to
8210: 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74   preallocate dat
8220: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70  abase.** file sp
8230: 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69  ace based on thi
8240: 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20  s hint in order 
8250: 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74  to help writes t
8260: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
8270: 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65  * file run faste
8280: 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  r..**.** <li>[[S
8290: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
82a0: 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20  K_SIZE]].** The 
82b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
82c0: 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65  UNK_SIZE] opcode
82d0: 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75   is used to requ
82e0: 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53  est that the VFS
82f0: 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20  .** extends and 
8300: 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61  truncates the da
8310: 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63  tabase file in c
8320: 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20  hunks of a size 
8330: 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
8340: 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f  the user. The fo
8350: 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
8360: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
8370: 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64  ontrol()] should
8380: 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e   .** point to an
8390: 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69   integer (type i
83a0: 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  nt) containing t
83b0: 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a  he new chunk-siz
83c0: 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20  e to use.** for 
83d0: 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61  the nominated da
83e0: 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69  tabase. Allocati
83f0: 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ng database file
8400: 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a   space in large.
8410: 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31  ** chunks (say 1
8420: 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d  MB at a time), m
8430: 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73  ay reduce file-s
8440: 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74  ystem fragmentat
8450: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f  ion and.** impro
8460: 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f  ve performance o
8470: 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a  n some systems..
8480: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
8490: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
84a0: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b  INTER]].** The [
84b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
84c0: 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  E_POINTER] opcod
84d0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
84e0: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
84f0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
8500: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
8510: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
8520: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
8530: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
8540: 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c  n.  See the [sql
8550: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8560: 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  l()] documentati
8570: 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  on for.** additi
8580: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
8590: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
85a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
85b0: 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54  OMITTED]].** ^(T
85c0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
85d0: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f  _SYNC_OMITTED] o
85e0: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
85f0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
8600: 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73  .** SQLite and s
8610: 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73  ent to all VFSes
8620: 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63   in place of a c
8630: 61 6c 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63  all to the xSync
8640: 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20   method.** when 
8650: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
8660: 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41  nection has [PRA
8670: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
8680: 20 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a   set to OFF.)^.*
8690: 2a 20 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a  * Some specializ
86a0: 65 64 20 56 46 53 65 73 20 6e 65 65 64 20 74 68  ed VFSes need th
86b0: 69 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64  is signal in ord
86c0: 65 72 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f  er to operate co
86d0: 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20  rrectly.** when 
86e0: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
86f0: 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e  ous | PRAGMA syn
8700: 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73  chronous=OFF] is
8710: 20 73 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a   set, but most .
8720: 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20  ** VFSes do not 
8730: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
8740: 20 61 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65   and should sile
8750: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
8760: 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c   opcode..** Appl
8770: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
8780: 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65  not call [sqlite
8790: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
87a0: 5d 20 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f  ] with this.** o
87b0: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
87c0: 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68  o may disrupt th
87d0: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  e operation of t
87e0: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
87f0: 46 53 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20  FSes.** that do 
8800: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
8810: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
8820: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
8830: 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20  RETRY]].** ^The 
8840: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
8850: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70  N32_AV_RETRY] op
8860: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
8870: 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61  configure automa
8880: 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75  tic.** retry cou
8890: 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c  nts and interval
88a0: 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69  s for certain di
88b0: 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  sk I/O operation
88c0: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e  s for the.** win
88d0: 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72  dows [VFS] in or
88e0: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72  der to provide r
88f0: 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65  obustness in the
8900: 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20   presence of.** 
8910: 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72  anti-virus progr
8920: 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ams.  By default
8930: 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46  , the windows VF
8940: 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c  S will retry fil
8950: 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20  e read,.** file 
8960: 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20  write, and file 
8970: 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e  delete operation
8980: 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73  s up to 10 times
8990: 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a  , with a delay.*
89a0: 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63  * of 25 millisec
89b0: 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20  onds before the 
89c0: 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20  first retry and 
89d0: 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69  with the delay i
89e0: 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20  ncreasing.** by 
89f0: 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35  an additional 25
8a00: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69   milliseconds wi
8a10: 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65  th each subseque
8a20: 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a  nt retry.  This.
8a30: 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73  ** opcode allows
8a40: 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65   these two value
8a50: 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e  s (10 retries an
8a60: 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  d 25 millisecond
8a70: 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74  s of delay).** t
8a80: 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20  o be adjusted.  
8a90: 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63  The values are c
8aa0: 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64  hanged for all d
8ab0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
8ac0: 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68  ons.** within th
8ad0: 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20  e same process. 
8ae0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
8af0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
8b00: 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a   array of two.**
8b10: 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20   integers where 
8b20: 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65  the first intege
8b30: 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72  r i the new retr
8b40: 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20  y count and the 
8b50: 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65  second.** intege
8b60: 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20  r is the delay. 
8b70: 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67   If either integ
8b80: 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
8b90: 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67  then the setting
8ba0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
8bb0: 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74  ed but instead t
8bc0: 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
8bd0: 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69  f that setting i
8be0: 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74  s written.** int
8bf0: 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72  o the array entr
8c00: 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20  y, allowing the 
8c10: 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65  current retry se
8c20: 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20  ttings to be.** 
8c30: 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54  interrogated.  T
8c40: 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d  he zDbName param
8c50: 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e  eter is ignored.
8c60: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8c70: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
8c80: 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20  T_WAL]].** ^The 
8c90: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
8ca0: 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64  RSIST_WAL] opcod
8cb0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
8cc0: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
8cd0: 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c   persistent [WAL
8ce0: 20 7c 20 57 72 69 74 65 20 41 48 65 61 64 20 4c   | Write AHead L
8cf0: 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79  og] setting.  By
8d00: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75   default, the au
8d10: 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65  xiliary.** write
8d20: 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73   ahead log and s
8d30: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
8d40: 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e  es used for tran
8d50: 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a  saction control.
8d60: 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ** are automatic
8d70: 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65  ally deleted whe
8d80: 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e  n the latest con
8d90: 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64  nection to the d
8da0: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65  atabase.** close
8db0: 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73  s.  Setting pers
8dc0: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
8dd0: 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c  causes those fil
8de0: 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66  es to persist af
8df0: 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50  ter.** close.  P
8e00: 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69  ersisting the fi
8e10: 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68  les is useful wh
8e20: 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  en other process
8e30: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a  es that do not.*
8e40: 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72  * have write per
8e50: 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64  mission on the d
8e60: 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e  irectory contain
8e70: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
8e80: 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f   file want.** to
8e90: 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61   read the databa
8ea0: 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20  se file, as the 
8eb0: 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d  WAL and shared m
8ec0: 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74  emory files must
8ed0: 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64   exist.** in ord
8ee0: 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  er for the datab
8ef0: 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62  ase to be readab
8f00: 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  le.  The fourth 
8f10: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
8f20: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
8f30: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
8f40: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
8f50: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
8f60: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
8f70: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
8f80: 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73   to disable pers
8f90: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
8fa0: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70  or 1 to enable p
8fb0: 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c  ersistent.** WAL
8fc0: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
8fd0: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
8fe0: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
8ff0: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
9000: 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72  rrent.** WAL per
9010: 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67  sistence setting
9020: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9030: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
9040: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d  SAFE_OVERWRITE]]
9050: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
9060: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
9070: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
9080: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
9090: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
90a0: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f  * persistent "po
90b0: 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74  wersafe-overwrit
90c0: 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74  e" or "PSOW" set
90d0: 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20  ting.  The PSOW 
90e0: 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72  setting.** deter
90f0: 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54  mines the [SQLIT
9100: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
9110: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74  E_OVERWRITE] bit
9120: 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69   of the.** xDevi
9130: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
9140: 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66  s methods. The f
9150: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
9160: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
9170: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
9180: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
9190: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
91a0: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
91b0: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
91c0: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
91d0: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  e zero-damage mo
91e0: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
91f0: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a  e zero-damage.**
9200: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
9210: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
9220: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
9230: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
9240: 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61  rrent.** zero-da
9250: 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e  mage mode settin
9260: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
9270: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
9280: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
9290: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
92a0: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
92b0: 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51  is invoked by SQ
92c0: 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69  Lite after openi
92d0: 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72  ng.** a write tr
92e0: 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64  ansaction to ind
92f0: 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65  icate that, unle
9300: 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20  ss it is rolled 
9310: 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a  back for some.**
9320: 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74   reason, the ent
9330: 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ire database fil
9340: 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72  e will be overwr
9350: 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72  itten by the cur
9360: 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63  rent .** transac
9370: 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73  tion. This is us
9380: 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65  ed by VACUUM ope
9390: 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c  rations..**.** <
93a0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
93b0: 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e  L_VFSNAME]].** ^
93c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
93d0: 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64  L_VFSNAME] opcod
93e0: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
93f0: 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65   obtain the name
9400: 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53  s of.** all [VFS
9410: 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73  es] in the VFS s
9420: 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73  tack.  The names
9430: 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20   are of all VFS 
9440: 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a  shims and the.**
9450: 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65   final bottom-le
9460: 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74  vel VFS are writ
9470: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
9480: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a  obtained from .*
9490: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
94a0: 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73  c()] and the res
94b0: 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e  ult is stored in
94c0: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
94d0: 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ble.** that the 
94e0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
94f0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   of [sqlite3_fil
9500: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69  e_control()] poi
9510: 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63  nts to..** The c
9520: 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73  aller is respons
9530: 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67  ible for freeing
9540: 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e   the memory when
9550: 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a   done.  As with.
9560: 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74  ** all file-cont
9570: 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  rol actions, the
9580: 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74  re is no guarant
9590: 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c  ee that this wil
95a0: 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f  l actually.** do
95b0: 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c   anything.  Call
95c0: 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69  ers should initi
95d0: 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20  alize the char* 
95e0: 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55  variable to a NU
95f0: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  LL.** pointer in
9600: 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d   case this file-
9610: 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69  control is not i
9620: 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69  mplemented.  Thi
9630: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  s file-control.*
9640: 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  * is intended fo
9650: 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65  r diagnostic use
9660: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   only..**.** <li
9670: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9680: 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65  PRAGMA]].** ^Whe
9690: 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d  never a [PRAGMA]
96a0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61   statement is pa
96b0: 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45  rsed, an [SQLITE
96c0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a  _FCNTL_PRAGMA] .
96d0: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
96e0: 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f  is sent to the o
96f0: 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  pen [sqlite3_fil
9700: 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73  e] object corres
9710: 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68  ponding.** to th
9720: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9730: 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61  to which the pra
9740: 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65  gma statement re
9750: 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d  fers. ^The argum
9760: 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53  ent.** to the [S
9770: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
9780: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
9790: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a   is an array of.
97a0: 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  ** pointers to s
97b0: 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20  trings (char**) 
97c0: 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63  in which the sec
97d0: 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74  ond element of t
97e0: 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74  he array.** is t
97f0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70  he name of the p
9800: 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68  ragma and the th
9810: 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74  ird element is t
9820: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  he argument to t
9830: 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20  he.** pragma or 
9840: 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67  NULL if the prag
9850: 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65  ma has no argume
9860: 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  nt.  ^The handle
9870: 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c  r for an.** [SQL
9880: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
9890: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63  ] file control c
98a0: 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61  an optionally ma
98b0: 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65  ke the first ele
98c0: 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63  ment.** of the c
98d0: 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70  har** argument p
98e0: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
98f0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
9900: 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
9910: 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75  )].** or the equ
9920: 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74  ivalent and that
9930: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63   string will bec
9940: 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ome the result o
9950: 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a  f the pragma or.
9960: 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ** the error mes
9970: 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67  sage if the prag
9980: 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68  ma fails. ^If th
9990: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
99a0: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
99b0: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
99c0: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
99d0: 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a  ], then normal .
99e0: 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63  ** [PRAGMA] proc
99f0: 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73  essing continues
9a00: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
9a10: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
9a20: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
9a30: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
9a40: 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70  _OK], then the p
9a50: 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68  arser assumes th
9a60: 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61  at the.** VFS ha
9a70: 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52  s handled the PR
9a80: 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20  AGMA itself and 
9a90: 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72  the parser gener
9aa0: 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20  ates a no-op.** 
9ab0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
9ac0: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51  nt.  ^If the [SQ
9ad0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
9ae0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
9af0: 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72  returns.** any r
9b00: 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72  esult code other
9b10: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
9b20: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  ] or [SQLITE_NOT
9b30: 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61  FOUND], that mea
9b40: 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56  ns.** that the V
9b50: 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61  FS encountered a
9b60: 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61  n error while ha
9b70: 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47  ndling the [PRAG
9b80: 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63  MA] and the.** c
9b90: 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68  ompilation of th
9ba0: 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77  e PRAGMA fails w
9bb0: 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
9bc0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9bd0: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
9be0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73  e control occurs
9bf0: 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   at the beginnin
9c00: 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74  g of pragma stat
9c10: 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61  ement analysis a
9c20: 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61  nd so.** it is a
9c30: 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20  ble to override 
9c40: 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41  built-in [PRAGMA
9c50: 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
9c60: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </ul>.*/.#defin
9c70: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
9c80: 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20  OCKSTATE        
9c90: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
9ca0: 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b   SQLITE_GET_LOCK
9cb0: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20  PROXYFILE       
9cc0: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
9cd0: 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50  SQLITE_SET_LOCKP
9ce0: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20  ROXYFILE        
9cf0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
9d00: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f  QLITE_LAST_ERRNO
9d10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
9d20: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
9d30: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
9d40: 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  HINT            
9d50: 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
9d60: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
9d70: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
9d80: 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
9d90: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
9da0: 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20  INTER           
9db0: 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
9dc0: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
9dd0: 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20  TTED            
9de0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
9df0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
9e00: 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39  RETRY          9
9e10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9e20: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
9e30: 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  L            10.
9e40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
9e50: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20  CNTL_OVERWRITE  
9e60: 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23              11.#
9e70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
9e80: 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20  NTL_VFSNAME     
9e90: 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64             12.#d
9ea0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
9eb0: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
9ec0: 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65  RWRITE    13.#de
9ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
9ee0: 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  L_PRAGMA        
9ef0: 20 20 20 20 20 20 20 20 20 31 34 0a 0a 2f 2a 0a           14../*.
9f00: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
9f10: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
9f20: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
9f30: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
9f40: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
9f50: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
9f60: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
9f70: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
9f80: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
9f90: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
9fa0: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
9fb0: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
9fc0: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
9fd0: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
9fe0: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
9ff0: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
a000: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
a010: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
a020: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
a030: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
a040: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
a050: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
a060: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
a070: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
a080: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
a090: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
a0a0: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
a0b0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
a0c0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
a0d0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
a0e0: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
a0f0: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
a100: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
a110: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
a120: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
a130: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
a140: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
a150: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
a160: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
a170: 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b  ".  See.** the [
a180: 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65  VFS | VFS docume
a190: 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72  ntation] for fur
a1a0: 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ther information
a1b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ..**.** The valu
a1c0: 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f  e of the iVersio
a1d0: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69  n field is initi
a1e0: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62  ally 1 but may b
a1f0: 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66  e larger in.** f
a200: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
a210: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74  f SQLite.  Addit
a220: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79  ional fields may
a230: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
a240: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77  this.** object w
a250: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e  hen the iVersion
a260: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61   value is increa
a270: 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  sed.  Note that 
a280: 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  the structure.**
a290: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
a2a0: 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67  vfs object chang
a2b0: 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61  es in the transa
a2c0: 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ction between.**
a2d0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
a2e0: 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20  3.5.9 and 3.6.0 
a2f0: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72  and yet the iVer
a300: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e  sion field was n
a310: 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a  ot.** modified..
a320: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
a330: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
a340: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
a350: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
a360: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
a370: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
a380: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
a390: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
a3a0: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
a3b0: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
a3c0: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
a3d0: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
a3e0: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
a3f0: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
a400: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
a410: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
a420: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
a430: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
a440: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
a450: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
a460: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
a470: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
a480: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
a490: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
a4a0: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
a4b0: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
a4c0: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
a4d0: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
a4e0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
a4f0: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
a500: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
a510: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
a520: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
a530: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
a540: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
a550: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
a560: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
a570: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
a580: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
a590: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
a5a0: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
a5b0: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
a5c0: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
a5d0: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
a5e0: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
a5f0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
a600: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
a610: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
a620: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
a630: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
a640: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
a650: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
a660: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
a670: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
a680: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
a690: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
a6a0: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
a6b0: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
a6c0: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
a6d0: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
a6e0: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53  fs.xOpen]].** ^S
a6f0: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
a700: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
a710: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
a720: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
a730: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
a740: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
a750: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
a760: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69  ullPathname() wi
a770: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73  th an optional s
a780: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20  uffix added..** 
a790: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20  ^If a suffix is 
a7a0: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69  added to the zFi
a7b0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
a7c0: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  , it will.** con
a7d0: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65  sist of a single
a7e0: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66   "-" character f
a7f0: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f  ollowed by no mo
a800: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c  re than.** 11 al
a810: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f  phanumeric and/o
a820: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73  r "-" characters
a830: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72  ..** ^SQLite fur
a840: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
a850: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
a860: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
a870: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
a880: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
a890: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
a8a0: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
a8b0: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
a8c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
a8d0: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
a8e0: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
a8f0: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
a900: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
a910: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
a920: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
a930: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
a940: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
a950: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69  meter to xOpen i
a960: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
a970: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
a980: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
a990: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
a9a0: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
a9b0: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a   ^Whenever the .
a9c0: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
a9d0: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
a9e0: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
a9f0: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
aa00: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
aa10: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
aa20: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
aa30: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
aa40: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
aa50: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
aa60: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
aa70: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
aa80: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
aa90: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
aaa0: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
aab0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
aac0: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
aad0: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
aae0: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
aaf0: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
ab00: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
ab10: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
ab20: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
ab30: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
ab40: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
ab50: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
ab60: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
ab70: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
ab80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
ab90: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
aba0: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
abb0: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
abc0: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c  ** ^(SQLite will
abd0: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
abe0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
abf0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
ac00: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
ac10: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
ac20: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
ac30: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
ac40: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
ac50: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
ac60: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ac70: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
ac80: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
ac90: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
aca0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
acb0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
acc0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
acd0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
ace0: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
acf0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
ad00: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
ad10: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
ad20: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
ad30: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ad40: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f  _OPEN_WAL].** </
ad50: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
ad60: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
ad70: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
ad80: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
ad90: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
ada0: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
adb0: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
adc0: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
add0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
ade0: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
adf0: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
ae00: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
ae10: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
ae20: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
ae30: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
ae40: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
ae50: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
ae60: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
ae70: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
ae80: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
ae90: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
aea0: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
aeb0: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
aec0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
aed0: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
aee0: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
aef0: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
af00: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
af10: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
af20: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
af30: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
af40: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
af50: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
af60: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
af70: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
af80: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
af90: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
afa0: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
afb0: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
afc0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
afd0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
afe0: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
aff0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
b000: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
b010: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b020: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
b030: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
b040: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
b050: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
b060: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
b070: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
b080: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
b090: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
b0a0: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61   for TEMP databa
b0b0: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f  ses and their jo
b0c0: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e  urnals, transien
b0d0: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20  t.** databases, 
b0e0: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  and subjournals.
b0f0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
b100: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
b110: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
b120: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
b130: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
b140: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
b150: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
b160: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
b170: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
b180: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
b190: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
b1a0: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
b1b0: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
b1c0: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
b1d0: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
b1e0: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
b1f0: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
b200: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
b210: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
b220: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
b230: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
b240: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
b250: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
b260: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
b270: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
b280: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
b290: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
b2a0: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
b2b0: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
b2c0: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
b2d0: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73  *.** ^At least s
b2e0: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
b2f0: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
b300: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
b310: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
b320: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
b330: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
b340: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
b350: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
b360: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
b370: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
b380: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
b390: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
b3a0: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
b3b0: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
b3c0: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
b3d0: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
b3e0: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
b3f0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
b400: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
b410: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
b420: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
b430: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
b440: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
b450: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
b460: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
b470: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
b480: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
b490: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
b4a0: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
b4b0: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
b4c0: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
b4d0: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
b4e0: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
b4f0: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
b500: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
b510: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a  _vfs.xAccess]].*
b520: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67  * ^The flags arg
b530: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
b540: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
b550: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
b560: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
b570: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
b580: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
b590: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
b5a0: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
b5b0: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
b5c0: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
b5d0: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
b5e0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
b5f0: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
b600: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
b610: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
b620: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
b630: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
b640: 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ry..**.** ^SQLit
b650: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
b660: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
b670: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
b680: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
b690: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
b6a0: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20  lPathname.  The 
b6b0: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68  exact size of th
b6c0: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
b6d0: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65  ** is also passe
b6e0: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72  d as a parameter
b6f0: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64   to both  method
b700: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  s. If the output
b710: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f   buffer.** is no
b720: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
b730: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
b740: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  ] should be retu
b750: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73  rned. Since this
b760: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61   is.** handled a
b770: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
b780: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69  by SQLite, vfs i
b790: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
b7a0: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a  hould endeavor.*
b7b0: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  * to prevent thi
b7c0: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50  s by setting mxP
b7d0: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
b7e0: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
b7f0: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
b800: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
b810: 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65  xSleep(), xCurre
b820: 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43  ntTime(), and xC
b830: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
b840: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
b850: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
b860: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
b870: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
b880: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
b890: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
b8a0: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
b8b0: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
b8c0: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
b8d0: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
b8e0: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
b8f0: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
b900: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
b910: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
b920: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
b930: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
b940: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
b950: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
b960: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
b970: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
b980: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
b990: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
b9a0: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
b9b0: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
b9c0: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
b9d0: 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78  s given.  ^The x
b9e0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
b9f0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
ba00: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
ba10: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
ba20: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
ba30: 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69  e as.** a floati
ba40: 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a  ng point value..
ba50: 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  ** ^The xCurrent
ba60: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
ba70: 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61  od returns, as a
ba80: 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a  n integer, the J
ba90: 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d  ulian.** Day Num
baa0: 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62  ber multiplied b
bab0: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20  y 86400000 (the 
bac0: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
bad0: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20  econds in .** a 
bae0: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a  24-hour day).  .
baf0: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
bb00: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74  use the xCurrent
bb10: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
bb20: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75  od to get the cu
bb30: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e  rrent.** date an
bb40: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d  d time if that m
bb50: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62  ethod is availab
bb60: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20  le (if iVersion 
bb70: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61  is 2 or .** grea
bb80: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63  ter and the func
bb90: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
bba0: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69  not NULL) and wi
bbb0: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20  ll fall back.** 
bbc0: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  to xCurrentTime(
bbd0: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d  ) if xCurrentTim
bbe0: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76  eInt64() is unav
bbf0: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ailable..**.** ^
bc00: 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61  The xSetSystemCa
bc10: 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d  ll(), xGetSystem
bc20: 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73  Call(), and xNes
bc30: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e  tSystemCall() in
bc40: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20  terfaces.** are 
bc50: 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20  not used by the 
bc60: 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68  SQLite core.  Th
bc70: 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74  ese optional int
bc80: 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
bc90: 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20  ided.** by some 
bca0: 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74  VFSes to facilit
bcb0: 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74  ate testing of t
bcc0: 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20  he VFS code. By 
bcd0: 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73  overriding .** s
bce0: 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68  ystem calls with
bcf0: 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72   functions under
bd00: 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20   its control, a 
bd10: 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e  test program can
bd20: 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75  .** simulate fau
bd30: 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f  lts and error co
bd40: 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f  nditions that wo
bd50: 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65  uld otherwise be
bd60: 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72   difficult.** or
bd70: 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69   impossible to i
bd80: 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20  nduce.  The set 
bd90: 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  of system calls 
bda0: 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
bdb0: 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73  ridden.** varies
bdc0: 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f   from one VFS to
bdd0: 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72   another, and fr
bde0: 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f  om one version o
bdf0: 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74  f the same VFS t
be00: 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20  o the.** next.  
be10: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
be20: 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65  t use these inte
be30: 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70  rfaces must be p
be40: 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a  repared for any.
be50: 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65  ** or all of the
be60: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f  se interfaces to
be70: 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20   be NULL or for 
be80: 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74  their behavior t
be90: 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d  o change.** from
bea0: 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20   one release to 
beb0: 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  the next.  Appli
bec0: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74  cations must not
bed0: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65   attempt to acce
bee0: 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65  ss.** any of the
bef0: 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68  se methods if th
bf00: 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68  e iVersion of th
bf10: 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68  e VFS is less th
bf20: 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  an 3..*/.typedef
bf30: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
bf40: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
bf50: 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
bf60: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
bf70: 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75  ptr)(void);.stru
bf80: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
bf90: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
bfa0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
bfb0: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
bfc0: 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74   number (current
bfd0: 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73  ly 3) */.  int s
bfe0: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
bff0: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
c000: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
c010: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
c020: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
c030: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
c040: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
c050: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
c060: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
c070: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
c080: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
c090: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
c0a0: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
c0b0: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
c0c0: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
c0d0: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
c0e0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
c0f0: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
c100: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
c110: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
c120: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
c130: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
c140: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
c150: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
c160: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
c170: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
c180: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
c190: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
c1a0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
c1b0: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
c1c0: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
c1d0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
c1e0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
c1f0: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
c200: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
c210: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
c220: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
c230: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
c240: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
c250: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
c260: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
c270: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
c280: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
c290: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
c2a0: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
c2b0: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
c2c0: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
c2d0: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
c2e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
c2f0: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
c300: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
c310: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
c320: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
c330: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
c340: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
c350: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
c360: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
c370: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
c380: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
c390: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
c3a0: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
c3b0: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
c3c0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
c3d0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
c3e0: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
c3f0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
c400: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20  char *);.  /*.  
c410: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
c420: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
c430: 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c  ion 1 of the sql
c440: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20  ite_vfs object. 
c450: 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   ** definition. 
c460: 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c   Those that foll
c470: 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20  ow are added in 
c480: 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74  version 2 or lat
c490: 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  er.  */.  int (*
c4a0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
c4b0: 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  4)(sqlite3_vfs*,
c4c0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29   sqlite3_int64*)
c4d0: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
c4e0: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
c4f0: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
c500: 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c  and 2 of the sql
c510: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
c520: 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77    ** Those below
c530: 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e   are for version
c540: 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a   3 and greater..
c550: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65    */.  int (*xSe
c560: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
c570: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
c580: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
c590: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
c5a0: 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79  r);.  sqlite3_sy
c5b0: 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74  scall_ptr (*xGet
c5c0: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
c5d0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
c5e0: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
c5f0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e  const char *(*xN
c600: 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  extSystemCall)(s
c610: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
c620: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
c630: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
c640: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
c650: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74   in versions 1 t
c660: 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20  hrough 3 of the 
c670: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
c680: 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
c690: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
c6a0: 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72  ed in figure ver
c6b0: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
c6c0: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
c6d0: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
c6e0: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
c6f0: 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
c700: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
c710: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
c720: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
c730: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
c740: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
c750: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
c760: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
c770: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
c780: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
c790: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
c7a0: 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
c7b0: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
c7c0: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
c7d0: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
c7e0: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
c7f0: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
c800: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
c810: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
c820: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
c830: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
c840: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
c850: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
c860: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
c870: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
c880: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
c890: 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
c8a0: 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
c8b0: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
c8c0: 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
c8d0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
c8e0: 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
c8f0: 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
c900: 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
c910: 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
c920: 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
c930: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
c940: 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
c950: 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
c960: 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
c970: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
c980: 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
c990: 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
c9a0: 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
c9b0: 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
c9c0: 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
c9d0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
c9e0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
c9f0: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
ca00: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
ca10: 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
ca20: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
ca30: 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
ca40: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
ca50: 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
ca60: 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
ca70: 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
ca80: 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
ca90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
caa0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
cab0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
cac0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
cad0: 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
cae0: 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
caf0: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
cb00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
cb10: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
cb20: 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
cb30: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
cb40: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
cb50: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
cb60: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
cb70: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
cb80: 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
cb90: 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
cba0: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
cbb0: 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
cbc0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
cbd0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
cbe0: 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
cbf0: 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
cc00: 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
cc10: 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
cc20: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
cc30: 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
cc40: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
cc50: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
cc60: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
cc70: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
cc80: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
cc90: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
cca0: 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
ccb0: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
ccc0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
ccd0: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
cce0: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
ccf0: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
cd00: 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
cd10: 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
cd20: 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
cd30: 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
cd40: 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
cd50: 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
cd60: 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f   given no the co
cd70: 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
cd80: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
cd90: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
cda0: 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
cdb0: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
cdc0: 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
cdd0: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
cde0: 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
cdf0: 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
ce00: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
ce10: 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
ce20: 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
ce30: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
ce40: 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
ce50: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
ce60: 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
ce70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
ce80: 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
ce90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
cea0: 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
ceb0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
cec0: 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
ced0: 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
cee0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
cef0: 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
cf00: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
cf10: 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
cf20: 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
cf30: 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
cf40: 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
cf50: 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
cf60: 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
cf70: 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
cf80: 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
cf90: 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
cfa0: 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
cfb0: 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
cfc0: 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
cfd0: 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
cfe0: 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
cff0: 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
d000: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
d010: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
d020: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
d030: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
d040: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
d050: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
d060: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
d070: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
d080: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
d090: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
d0a0: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
d0b0: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
d0c0: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
d0d0: 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
d0e0: 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
d0f0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
d100: 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
d110: 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
d120: 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
d130: 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
d140: 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
d150: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
d160: 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
d170: 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
d180: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
d190: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
d1a0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
d1b0: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
d1c0: 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
d1d0: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
d1e0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d1f0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
d200: 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
d210: 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
d220: 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
d230: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
d240: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
d250: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
d260: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
d270: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
d280: 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
d290: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
d2a0: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
d2b0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
d2c0: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
d2d0: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
d2e0: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
d2f0: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
d300: 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
d310: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
d320: 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
d330: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
d340: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
d350: 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
d360: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
d370: 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
d380: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d390: 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
d3a0: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
d3b0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
d3c0: 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
d3d0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
d3e0: 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
d3f0: 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
d400: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
d410: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
d420: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
d430: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
d440: 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
d450: 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
d460: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
d470: 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
d480: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
d490: 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
d4a0: 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
d4b0: 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
d4c0: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
d4d0: 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
d4e0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
d4f0: 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
d500: 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
d510: 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
d520: 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
d530: 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
d540: 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
d550: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
d560: 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
d570: 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
d580: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
d590: 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
d5a0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
d5b0: 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
d5c0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
d5d0: 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
d5e0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
d5f0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
d600: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d610: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
d620: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
d630: 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
d640: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
d650: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
d660: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
d670: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
d680: 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
d690: 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
d6a0: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
d6b0: 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
d6c0: 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
d6d0: 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
d6e0: 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
d6f0: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
d700: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
d710: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
d720: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
d730: 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
d740: 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
d750: 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
d760: 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
d770: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
d780: 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
d790: 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
d7a0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
d7b0: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
d7c0: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
d7d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
d7e0: 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
d7f0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
d800: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
d810: 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
d820: 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
d830: 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
d840: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
d850: 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
d860: 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
d870: 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
d880: 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
d890: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
d8a0: 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
d8b0: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
d8c0: 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
d8d0: 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
d8e0: 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
d8f0: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
d900: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
d910: 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
d920: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
d930: 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
d940: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
d950: 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
d960: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
d970: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
d980: 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
d990: 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
d9a0: 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
d9b0: 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
d9c0: 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
d9d0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
d9e0: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
d9f0: 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
da00: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
da10: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
da20: 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
da30: 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
da40: 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
da50: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
da60: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
da70: 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
da80: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
da90: 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
daa0: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
dab0: 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
dac0: 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
dad0: 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
dae0: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
daf0: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
db00: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
db10: 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
db20: 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
db30: 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
db40: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
db50: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
db60: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
db70: 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
db80: 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
db90: 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
dba0: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
dbb0: 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
dbc0: 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
dbd0: 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
dbe0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
dbf0: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
dc00: 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
dc10: 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
dc20: 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
dc30: 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
dc40: 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
dc50: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
dc60: 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
dc70: 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
dc80: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
dc90: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
dca0: 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
dcb0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
dcc0: 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
dcd0: 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
dce0: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
dcf0: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
dd00: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
dd10: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
dd20: 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
dd30: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
dd40: 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
dd50: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
dd60: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
dd70: 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
dd80: 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
dd90: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
dda0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ddb0: 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
ddc0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
ddd0: 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
dde0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
ddf0: 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
de00: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
de10: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
de20: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
de30: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
de40: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
de50: 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
de60: 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
de70: 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
de80: 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
de90: 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
dea0: 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
deb0: 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
dec0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
ded0: 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
dee0: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
def0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
df00: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
df10: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
df20: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
df30: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
df40: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
df50: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
df60: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
df70: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
df80: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
df90: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
dfa0: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
dfb0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
dfc0: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
dfd0: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
dfe0: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
dff0: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
e000: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
e010: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
e020: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
e030: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
e040: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
e050: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
e060: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
e070: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
e080: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
e090: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
e0a0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
e0b0: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
e0c0: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
e0d0: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
e0e0: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
e0f0: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
e100: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
e110: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
e120: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
e130: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
e140: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
e150: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
e160: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
e170: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
e180: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
e190: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
e1a0: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
e1b0: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
e1c0: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
e1d0: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
e1e0: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
e1f0: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  needs..**.** The
e200: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
e210: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
e220: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  ot threadsafe.  
e230: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
e240: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  ** must insure t
e250: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
e260: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
e270: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
e280: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
e290: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
e2a0: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
e2b0: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20  .  Furthermore, 
e2c0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e2d0: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
e2e0: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
e2f0: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
e300: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
e310: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
e320: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
e330: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
e340: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
e350: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
e360: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
e370: 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
e380: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
e390: 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
e3a0: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
e3b0: 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
e3c0: 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
e3d0: 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
e3e0: 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
e3f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e400: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
e410: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
e420: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
e430: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
e440: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
e450: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
e460: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
e470: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
e480: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
e490: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f  n integer.** [co
e4a0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
e4b0: 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69  on] that determi
e4c0: 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70  nes.** what prop
e4d0: 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69  erty of SQLite i
e4e0: 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72  s to be configur
e4f0: 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  ed.  Subsequent 
e500: 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72  arguments.** var
e510: 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
e520: 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  he [configuratio
e530: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
e540: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
e550: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
e560: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
e570: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
e580: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
e590: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
e5a0: 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
e5b0: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
e5c0: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
e5d0: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
e5e0: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
e5f0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
e600: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
e610: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
e620: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  .int sqlite3_con
e630: 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a  fig(int, ...);..
e640: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
e650: 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61  Configure databa
e660: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
e670: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
e680: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
e690: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
e6a0: 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61  o make configura
e6b0: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
e6c0: 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  to a [database c
e6d0: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
e6e0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69   interface is si
e6f0: 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  milar to.** [sql
e700: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65  ite3_config()] e
e710: 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63  xcept that the c
e720: 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20  hanges apply to 
e730: 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74  a single.** [dat
e740: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e750: 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20  ] (specified in 
e760: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
e770: 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  nt)..**.** The s
e780: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
e790: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
e7a0: 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73  fig(D,V,...)  is
e7b0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
e7c0: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
e7d0: 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  DE | configurati
e7e0: 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e  on verb] - an in
e7f0: 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74  teger code .** t
e800: 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68  hat indicates wh
e810: 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  at aspect of the
e820: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
e830: 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
e840: 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53  configured..** S
e850: 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
e860: 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69  nts vary dependi
e870: 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67  ng on the config
e880: 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a  uration verb..**
e890: 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71  .** ^Calls to sq
e8a0: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
e8b0: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
e8c0: 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  OK if and only i
e8d0: 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73  f.** the call is
e8e0: 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63   considered succ
e8f0: 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  essful..*/.int s
e900: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
e910: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
e920: 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  p, ...);../*.** 
e930: 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
e940: 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74   Allocation Rout
e950: 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ines.**.** An in
e960: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
e970: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
e980: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
e990: 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e  een SQLite.** an
e9a0: 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  d low-level memo
e9b0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
e9c0: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
e9d0: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  is object is use
e9e0: 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c  d in only one pl
e9f0: 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74  ace in the SQLit
ea00: 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
ea10: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
ea20: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
ea30: 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61   object is the a
ea40: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73  rgument to.** [s
ea50: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
ea60: 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67   when the config
ea70: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
ea80: 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  s.** [SQLITE_CON
ea90: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b  FIG_MALLOC] or [
eaa0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
eab0: 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42  TMALLOC].  .** B
eac0: 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e  y creating an in
ead0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
eae0: 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73  bject.** and pas
eaf0: 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
eb00: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
eb10: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
eb20: 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f  C]).** during co
eb30: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20  nfiguration, an 
eb40: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20  application can 
eb50: 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
eb60: 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
eb70: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
eb80: 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65  ystem for SQLite
eb90: 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20   to use for all 
eba0: 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69  of its.** dynami
ebb0: 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a  c memory needs..
ebc0: 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
ebd0: 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74  SQLite comes wit
ebe0: 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74  h several [built
ebf0: 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
ec00: 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61  ators].** that a
ec10: 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65  re perfectly ade
ec20: 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76  quate for the ov
ec30: 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72  erwhelming major
ec40: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
ec50: 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ons.** and that 
ec60: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f  this object is o
ec70: 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20  nly useful to a 
ec80: 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66  tiny minority of
ec90: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
eca0: 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65   with specialize
ecb0: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
ecc0: 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73  ion requirements
ecd0: 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  .  This object i
ece0: 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64  s.** also used d
ecf0: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66  uring testing of
ed00: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
ed10: 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61   to specify an a
ed20: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
ed30: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74  mory allocator t
ed40: 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65  hat simulates me
ed50: 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f  mory out-of-memo
ed60: 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e  ry conditions in
ed70: 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72  .** order to ver
ed80: 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20  ify that SQLite 
ed90: 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75  recovers gracefu
eda0: 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a  lly from such.**
edb0: 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a   conditions..**.
edc0: 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20  ** The xMalloc, 
edd0: 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46  xRealloc, and xF
ede0: 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74  ree methods must
edf0: 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a   work like the.*
ee00: 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c  * malloc(), real
ee10: 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
ee20: 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20   functions from 
ee30: 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
ee40: 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  ibrary..** ^SQLi
ee50: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
ee60: 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  at the second ar
ee70: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65  gument to.** xRe
ee80: 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20  alloc is always 
ee90: 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  a value returned
eea0: 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c   by a prior call
eeb0: 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a   to xRoundup..**
eec0: 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64  .** xSize should
eed0: 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f   return the allo
eee0: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20  cated size of a 
eef0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
ef00: 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  n.** previously 
ef10: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d  obtained from xM
ef20: 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f  alloc or xReallo
ef30: 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65  c.  The allocate
ef40: 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77  d size.** is alw
ef50: 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20  ays at least as 
ef60: 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65  big as the reque
ef70: 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61  sted size but ma
ef80: 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a  y be larger..**.
ef90: 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20  ** The xRoundup 
efa0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77  method returns w
efb0: 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65  hat would be the
efc0: 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
efd0: 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61  of.** a memory a
efe0: 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20  llocation given 
eff0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71  a particular req
f000: 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f  uested size.  Mo
f010: 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  st memory.** all
f020: 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
f030: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
f040: 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20  ons at least to 
f050: 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c  the next multipl
f060: 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65  e.** of 8.  Some
f070: 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
f080: 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72  d up to a larger
f090: 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20   multiple or to 
f0a0: 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a  a power of 2..**
f0b0: 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c   Every memory al
f0c0: 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74  location request
f0d0: 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75   coming in throu
f0e0: 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  gh [sqlite3_mall
f0f0: 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  oc()].** or [sql
f100: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
f110: 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75  first calls xRou
f120: 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64  ndup.  If xRound
f130: 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a  up returns 0, .*
f140: 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68  * that causes th
f150: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
f160: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
f170: 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a  n to fail..**.**
f180: 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   The xInit metho
f190: 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  d initializes th
f1a0: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
f1b0: 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c  or.  (For exampl
f1c0: 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61  e,.** it might a
f1d0: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75  llocate any requ
f1e0: 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69  ire mutexes or i
f1f0: 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e  nitialize intern
f200: 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63  al data.** struc
f210: 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75  tures.  The xShu
f220: 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
f230: 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63  invoked (indirec
f240: 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  tly) by.** [sqli
f250: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
f260: 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c  and should deall
f270: 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72  ocate any resour
f280: 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20  ces acquired.** 
f290: 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70  by xInit.  The p
f2a0: 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20  AppData pointer 
f2b0: 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f  is used as the o
f2c0: 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
f2d0: 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53  .** xInit and xS
f2e0: 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53  hutdown..**.** S
f2f0: 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20  QLite holds the 
f300: 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
f310: 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74  ATIC_MASTER] mut
f320: 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b  ex when it invok
f330: 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20  es.** the xInit 
f340: 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78  method, so the x
f350: 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64  Init method need
f360: 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61   not be threadsa
f370: 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75  fe.  The.** xShu
f380: 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
f390: 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d  only called from
f3a0: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
f3b0: 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73  wn()] so it does
f3c0: 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  .** not need to 
f3d0: 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69  be threadsafe ei
f3e0: 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f  ther.  For all o
f3f0: 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51  ther methods, SQ
f400: 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68  Lite.** holds th
f410: 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
f420: 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65  STATIC_MEM] mute
f430: 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  x as long as the
f440: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
f450: 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f  IG_MEMSTATUS] co
f460: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
f470: 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20  on is turned on 
f480: 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20  (which.** it is 
f490: 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20  by default) and 
f4a0: 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61  so the methods a
f4b0: 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
f4c0: 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20   serialized..** 
f4d0: 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c  However, if [SQL
f4e0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
f4f0: 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65  ATUS] is disable
f500: 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65  d, then the othe
f510: 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73  r.** methods mus
f520: 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  t be threadsafe 
f530: 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65  or else make the
f540: 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65  ir own arrangeme
f550: 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61  nts for.** seria
f560: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  lization..**.** 
f570: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
f580: 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29  r invoke xInit()
f590: 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20   more than once 
f5a0: 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72  without an inter
f5b0: 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74  vening.** call t
f5c0: 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  o xShutdown()..*
f5d0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
f5e0: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
f5f0: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d  hods sqlite3_mem
f600: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
f610: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
f620: 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28  hods {.  void *(
f630: 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20  *xMalloc)(int); 
f640: 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72          /* Memor
f650: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e  y allocation fun
f660: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
f670: 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b  (*xFree)(void*);
f680: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65            /* Fre
f690: 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  e a prior alloca
f6a0: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
f6b0: 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64  (*xRealloc)(void
f6c0: 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69  *,int);  /* Resi
f6d0: 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze an allocation
f6e0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a   */.  int (*xSiz
f6f0: 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
f700: 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74       /* Return t
f710: 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c  he size of an al
f720: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
f730: 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e  t (*xRoundup)(in
f740: 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t);          /* 
f750: 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74  Round up request
f760: 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74   size to allocat
f770: 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e  ion size */.  in
f780: 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a  t (*xInit)(void*
f790: 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
f7a0: 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  Initialize the m
f7b0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
f7c0: 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75  */.  void (*xShu
f7d0: 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20  tdown)(void*);  
f7e0: 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c      /* Deinitial
f7f0: 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
f800: 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
f810: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
f820: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
f830: 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69  Argument to xIni
f840: 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77  t() and xShutdow
f850: 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  n() */.};../*.**
f860: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
f870: 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
f880: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
f890: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
f8a0: 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion}.**.** These
f8b0: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
f8c0: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
f8d0: 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
f8e0: 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
f8f0: 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
f900: 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
f910: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
f920: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
f930: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
f940: 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
f950: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
f960: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
f970: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
f980: 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
f990: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
f9a0: 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
f9b0: 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
f9c0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
f9d0: 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
f9e0: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
f9f0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  om [sqlite3_conf
fa00: 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
fa10: 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
fa20: 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65  all worked.  The
fa30: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
fa40: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
fa50: 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
fa60: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
fa70: 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
fa80: 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
fa90: 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
faa0: 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
fab0: 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
fac0: 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
fad0: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
fae0: 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
faf0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
fb00: 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
fb10: 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
fb20: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
fb30: 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
fb40: 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
fb50: 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
fb60: 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68  de] to Single-th
fb70: 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
fb80: 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
fb90: 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69  es.** all mutexi
fba0: 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69  ng and puts SQLi
fbb0: 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77  te into a mode w
fbc0: 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79  here it can only
fbd0: 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61   be used.** by a
fbe0: 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
fbf0: 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
fc00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
fc10: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
fc20: 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
fc30: 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
fc40: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
fc50: 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
fc60: 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
fc70: 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72   change the [thr
fc80: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f  eading mode] fro
fc90: 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a  m its default.**
fca0: 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65   value of Single
fcb0: 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b  -thread and so [
fcc0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
fcd0: 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a  ] will return .*
fce0: 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
fcf0: 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
fd00: 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
fd10: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a  G_SINGLETHREAD.*
fd20: 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
fd30: 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
fd40: 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
fd50: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d  IG_MULTITHREAD]]
fd60: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
fd70: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f  IG_MULTITHREAD</
fd80: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
fd90: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
fda0: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
fdb0: 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
fdc0: 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
fdd0: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
fde0: 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49  Multi-thread.  I
fdf0: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
fe00: 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  t disables.** mu
fe10: 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
fe20: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
fe30: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
fe40: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
fe50: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
fe60: 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
fe70: 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
fe80: 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
fe90: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
fea0: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
feb0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
fec0: 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
fed0: 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
fee0: 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
fef0: 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
ff00: 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
ff10: 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
ff20: 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f  nvironment as lo
ff30: 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72  ng as no two thr
ff40: 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20  eads attempt to 
ff50: 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
ff60: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
ff70: 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d  tion] at the sam
ff80: 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c  e time.  ^If SQL
ff90: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
ffa0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
ffb0: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
ffc0: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
ffd0: 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
ffe0: 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
fff0: 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
10000 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
10010 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  Multi-thread [th
10020 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
10030 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
10040 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
10050 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
10060 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
10070 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
10080 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
10090 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  AD configuration
100a0 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
100b0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
100c0 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d  FIG_SERIALIZED]]
100d0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
100e0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64  IG_SERIALIZED</d
100f0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
10100 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
10110 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
10120 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
10130 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
10140 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
10150 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74  erialized. In ot
10160 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20  her words, this 
10170 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a  option enables.*
10180 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e  * all mutexes in
10190 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75  cluding the recu
101a0 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73  rsive.** mutexes
101b0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
101c0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
101d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
101e0 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49  t] objects..** I
101f0 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69  n this mode (whi
10200 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
10210 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  t when SQLite is
10220 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
10230 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
10240 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c  SAFE=1]) the SQL
10250 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
10260 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a   itself serializ
10270 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b  e access.** to [
10280 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10290 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
102a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
102b0 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61  so that the.** a
102c0 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72  pplication is fr
102d0 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  ee to use the sa
102e0 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
102f0 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a  nection] or the.
10300 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  ** same [prepare
10310 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
10320 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
10330 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  s at the same ti
10340 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  me..** ^If SQLit
10350 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
10360 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
10370 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
10380 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
10390 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
103a0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
103b0 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
103c0 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65  le to set the Se
103d0 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
103e0 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
103f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
10400 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
10410 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
10420 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
10430 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
10440 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f  IG_SERIALIZED co
10450 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10460 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
10470 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
10480 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
10490 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
104a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
104b0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
104c0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
104d0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
104e0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
104f0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
10500 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
10510 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
10520 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
10530 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
10540 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
10550 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
10560 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
10570 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
10580 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
10590 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
105a0 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
105b0 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69   SQLite.)^ ^SQLi
105c0 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20  te makes.** its 
105d0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
105e0 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
105f0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
10600 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
10610 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65  ucture.** before
10620 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
10630 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74  nfig()] call ret
10640 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  urns.</dd>.**.**
10650 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
10660 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  _GETMALLOC]] <dt
10670 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
10680 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
10690 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
106a0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
106b0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
106c0 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
106d0 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
106e0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
106f0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
10700 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73  ructure.  The [s
10710 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
10720 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
10730 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
10740 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
10750 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  fined memory all
10760 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
10770 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
10780 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
10790 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
107a0 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
107b0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
107c0 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
107d0 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  per that simulat
107e0 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ions memory allo
107f0 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f  cation failure o
10800 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f  r.** tracks memo
10810 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78  ry usage, for ex
10820 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ample. </dd>.**.
10830 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
10840 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c  IG_MEMSTATUS]] <
10850 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
10860 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a  _MEMSTATUS</dt>.
10870 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
10880 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
10890 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
108a0 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65  pe int, interpre
108b0 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f  ted as a .** boo
108c0 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
108d0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
108e0 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
108f0 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
10900 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69  ion .** statisti
10910 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72  cs. ^(When memor
10920 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
10930 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
10940 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f  bled, the .** fo
10950 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69  llowing SQLite i
10960 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65  nterfaces become
10970 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
10980 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
10990 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
109a0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
109b0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
109c0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
109d0 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
109e0 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
109f0 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20  p_limit64()].** 
10a00 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
10a10 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c  status()].**   <
10a20 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
10a30 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
10a40 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
10a50 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
10a60 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
10a70 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
10a80 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
10a90 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
10aa0 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
10ab0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
10ac0 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
10ad0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
10ae0 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
10af0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
10b00 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64  FIG_SCRATCH]] <d
10b10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10b20 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
10b30 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
10b40 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
10b50 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
10b60 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
10b70 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63  an use for.** sc
10b80 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54  ratch memory.  T
10b90 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
10ba0 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69  rguments:  A poi
10bb0 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a  nter an 8-byte.*
10bc0 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  * aligned memory
10bd0 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69   buffer from whi
10be0 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61  ch the scratch a
10bf0 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20  llocations will 
10c00 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65  be.** drawn, the
10c10 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63   size of each sc
10c20 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
10c30 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68   (sz),.** and th
10c40 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
10c50 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f   of scratch allo
10c60 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68  cations (N).  Th
10c70 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  e sz.** argument
10c80 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69   must be a multi
10c90 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68  ple of 16..** Th
10ca0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10cb0 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74   must be a point
10cc0 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  er to an 8-byte 
10cd0 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a  aligned buffer.*
10ce0 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  * of at least sz
10cf0 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
10d00 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
10d10 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20  ill use no more 
10d20 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68  than two scratch
10d30 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72   buffers per thr
10d40 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68  ead.  So.** N sh
10d50 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74  ould be set to t
10d60 77 69 63 65 20 74 68 65 20 65 78 70 65 63 74 65  wice the expecte
10d70 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  d maximum number
10d80 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20   of threads..** 
10d90 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76  ^SQLite will nev
10da0 65 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72  er require a scr
10db0 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74  atch buffer that
10dc0 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a   is more than 6.
10dd0 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74  ** times the dat
10de0 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e  abase page size.
10df0 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64   ^If SQLite need
10e00 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e  s needs addition
10e10 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65  al.** scratch me
10e20 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74  mory beyond what
10e30 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
10e40 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  this configurati
10e50 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  on option, then 
10e60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
10e70 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75  loc()] will be u
10e80 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
10e90 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e  e memory needed.
10ea0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
10eb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
10ec0 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CACHE]] <dt>SQLI
10ed0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
10ee0 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
10ef0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
10f00 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
10f10 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
10f20 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
10f30 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61  se for.** the da
10f40 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68  tabase page cach
10f50 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75  e with the defau
10f60 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  lt page cache im
10f70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a  plementation.  .
10f80 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
10f90 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
10fa0 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61   be used if an a
10fb0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
10fc0 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
10fd0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
10fe0 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
10ff0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
11000 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e  _PCACHE2 option.
11010 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68  .** There are th
11020 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
11030 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20   this option: A 
11040 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74  pointer to 8-byt
11050 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d  e aligned.** mem
11060 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  ory, the size of
11070 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65   each page buffe
11080 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20  r (sz), and the 
11090 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
110a0 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61  (N)..** The sz a
110b0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
110c0 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  e the size of th
110d0 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61  e largest databa
110e0 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f  se page.** (a po
110f0 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65  wer of two betwe
11100 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38  en 512 and 32768
11110 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20  ) plus a little 
11120 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a  extra for each.*
11130 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20  * page header.  
11140 5e 54 68 65 20 70 61 67 65 20 68 65 61 64 65 72  ^The page header
11150 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34   size is 20 to 4
11160 30 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e  0 bytes dependin
11170 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74  g on.** the host
11180 20 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 20   architecture.  
11190 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c  ^It is harmless,
111a0 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20   apart from the 
111b0 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a  wasted memory,.*
111c0 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c  * to make sz a l
111d0 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e  ittle too large.
111e0 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61    The first.** a
111f0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70  rgument should p
11200 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63  oint to an alloc
11210 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73  ation of at leas
11220 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
11230 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
11240 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
11250 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20  memory provided 
11260 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
11270 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79  ument to satisfy
11280 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e   its.** memory n
11290 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72  eeds for the fir
112a0 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20  st N pages that 
112b0 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65  it adds to cache
112c0 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61  .  ^If additiona
112d0 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  l.** page cache 
112e0 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64  memory is needed
112f0 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
11300 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
11310 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a   option, then.**
11320 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
11330 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
11340 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74  )] for the addit
11350 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70  ional storage sp
11360 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ace..** The poin
11370 74 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  ter in the first
11380 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a   argument must.*
11390 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  * be aligned to 
113a0 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61  an 8-byte bounda
113b0 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
113c0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
113d0 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75  ite.** will be u
113e0 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a  ndefined.</dd>.*
113f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11400 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e  NFIG_HEAP]] <dt>
11410 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
11420 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  AP</dt>.** <dd> 
11430 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
11440 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
11450 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
11460 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  at SQLite will u
11470 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66  se.** for all of
11480 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
11490 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
114a0 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73  eeds beyond thos
114b0 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f  e provided.** fo
114c0 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
114d0 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64  FIG_SCRATCH] and
114e0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
114f0 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54  PAGECACHE]..** T
11500 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
11510 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62  rguments: An 8-b
11520 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
11530 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
11540 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
11550 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
11560 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
11570 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
11580 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
11590 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
115a0 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
115b0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
115c0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
115d0 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
115e0 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
115f0 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
11600 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
11610 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
11620 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
11630 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
11640 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
11650 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
11660 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
11670 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
11680 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
11690 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
116a0 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
116b0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  or.** [SQLITE_EN
116c0 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72  ABLE_MEMSYS5] ar
116d0 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20  e defined, then 
116e0 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
116f0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
11700 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
11710 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
11720 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
11730 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
11740 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
11750 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
11760 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
11770 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
11780 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
11790 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
117a0 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
117b0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
117c0 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d  efined..** The m
117d0 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
117e0 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64  n size is capped
117f0 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f   at 2**12. Reaso
11800 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20  nable values.** 
11810 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  for the minimum 
11820 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
11830 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68  are 2**5 through
11840 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   2**8.</dd>.**.*
11850 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
11860 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  G_MUTEX]] <dt>SQ
11870 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
11880 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
11890 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
118a0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
118b0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
118c0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
118d0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
118e0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
118f0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
11900 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
11910 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
11920 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
11930 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
11940 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
11950 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d  n place.** the m
11960 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
11970 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
11980 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
11990 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
119a0 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  ** content of th
119b0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
119c0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
119d0 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63  ure before the c
119e0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
119f0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74  e3_config()] ret
11a00 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65  urns. ^If SQLite
11a10 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
11a20 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
11a30 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
11a40 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
11a50 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
11a60 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
11a70 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
11a80 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
11a90 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
11aa0 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
11ab0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
11ac0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11ad0 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
11ae0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e  CONFIG_MUTEX con
11af0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11b00 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
11b10 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
11b20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
11b30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
11b40 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
11b50 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
11b60 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
11b70 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
11b80 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
11b90 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
11ba0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
11bb0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
11bc0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
11bd0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
11be0 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  re.  The.** [sql
11bf0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
11c00 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
11c10 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
11c20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
11c30 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74  fined mutex rout
11c40 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
11c50 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
11c60 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
11c70 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
11c80 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
11c90 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
11ca0 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74  rapper used to t
11cb0 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65  rack mutex usage
11cc0 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
11cd0 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72  .** profiling or
11ce0 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78   testing, for ex
11cf0 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c  ample.   ^If SQL
11d00 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11d10 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
11d20 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
11d30 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
11d40 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
11d50 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
11d60 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
11d70 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
11d80 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
11d90 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
11da0 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
11db0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11dc0 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
11dd0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
11de0 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
11df0 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
11e00 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
11e10 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
11e20 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
11e30 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64  G_LOOKASIDE]] <d
11e40 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11e50 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
11e60 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
11e70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
11e80 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
11e90 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61  termine the defa
11ea0 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ult.** memory al
11eb0 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  location for the
11ec0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
11ed0 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65  y allocator on e
11ee0 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
11ef0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
11f00 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
11f10 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
11f20 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
11f30 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
11f40 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
11f50 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
11f60 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
11f70 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
11f80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e  se connection.)^
11f90 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20    ^(This option 
11fa0 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64  sets the.** <i>d
11fb0 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61  efault</i> looka
11fc0 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b  side size. The [
11fd0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
11fe0 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65  LOOKASIDE].** ve
11ff0 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  rb to [sqlite3_d
12000 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20  b_config()] can 
12010 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  be used to chang
12020 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
12030 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
12040 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63   on individual c
12050 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f  onnections.)^ </
12060 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
12070 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
12080 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
12090 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64  ONFIG_PCACHE2</d
120a0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
120b0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
120c0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
120d0 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
120e0 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71  ter to.** an [sq
120f0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
12100 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
12110 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
12120 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66  ifies the interf
12130 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74  ace.** to a cust
12140 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
12150 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20  plementation.)^ 
12160 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
12170 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
12180 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20  object and uses 
12190 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68  it for page cach
121a0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
121b0 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ions.</dd>.**.**
121c0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
121d0 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64  _GETPCACHE2]] <d
121e0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
121f0 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  GETPCACHE2</dt>.
12200 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
12210 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
12220 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
12230 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
12240 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
12250 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
12260 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c  s2] object.  SQL
12270 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68  ite copies of th
12280 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67  e current.** pag
12290 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
122a0 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74  tation into that
122b0 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e   object.)^ </dd>
122c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
122d0 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74  CONFIG_LOG]] <dt
122e0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
122f0 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OG</dt>.** <dd> 
12300 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
12310 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61  IG_LOG option ta
12320 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
12330 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: a pointer to 
12340 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  a.** function wi
12350 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74  th a call signat
12360 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76  ure of void(*)(v
12370 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
12380 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61  har*), .** and a
12390 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64   pointer to void
123a0 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  . ^If the functi
123b0 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
123c0 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a  t NULL, it is.**
123d0 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c   invoked by [sql
123e0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70  ite3_log()] to p
123f0 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67  rocess each logg
12400 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
12410 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
12420 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c  pointer is NULL,
12430 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
12440 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  g()] interface b
12450 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a  ecomes a no-op..
12460 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69  ** ^The void poi
12470 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65  nter that is the
12480 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
12490 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
124a0 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73  G_LOG is.** pass
124b0 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
124c0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
124d0 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  r to the applica
124e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
124f0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
12500 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75  whenever that fu
12510 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
12520 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  d.  ^The second 
12530 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
12540 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
12550 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ion is a copy of
12560 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
12570 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72  eter to the corr
12580 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71  esponding.** [sq
12590 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c  lite3_log()] cal
125a0 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65  l and is intende
125b0 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c  d to be a [resul
125c0 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  t code] or an.**
125d0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
125e0 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74  t code].  ^The t
125f0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70  hird parameter p
12600 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67  assed to the log
12610 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65  ger is.** log me
12620 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d  ssage after form
12630 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69  atting via [sqli
12640 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e  te3_snprintf()].
12650 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c  .** The SQLite l
12660 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65  ogging interface
12670 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
12680 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  t; the logger fu
12690 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  nction.** suppli
126a0 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
126b0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69  ation must not i
126c0 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65  nvoke any SQLite
126d0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
126e0 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
126f0 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  ed application, 
12700 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
12710 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
12720 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
12730 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c  be threadsafe. <
12740 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12750 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d  ITE_CONFIG_URI]]
12760 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12770 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54  IG_URI.** <dd> T
12780 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
12790 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
127a0 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20  nt of type int. 
127b0 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  If non-zero, the
127c0 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e  n.** URI handlin
127d0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
127e0 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61  abled. If the pa
127f0 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c  rameter is zero,
12800 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
12810 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c  ng.** is globall
12820 79 20 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55  y disabled. If U
12830 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
12840 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c  lobally enabled,
12850 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a   all filenames.*
12860 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  * passed to [sql
12870 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
12880 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
12890 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
128a0 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63  16()] or.** spec
128b0 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66  ified as part of
128c0 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e   [ATTACH] comman
128d0 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  ds are interpret
128e0 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61  ed as URIs, rega
128f0 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65  rdless.** of whe
12900 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
12910 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
12920 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  ] flag is set wh
12930 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  en the database.
12940 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
12950 20 6f 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69   opened. If it i
12960 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
12970 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61  led, filenames a
12980 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72  re.** only inter
12990 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69  preted as URIs i
129a0 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  f the SQLITE_OPE
129b0 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65  N_URI flag is se
129c0 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61  t when the.** da
129d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
129e0 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20  n is opened. By 
129f0 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e  default, URI han
12a00 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
12a10 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54  y.** disabled. T
12a20 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
12a30 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20   may be changed 
12a40 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74  by compiling wit
12a50 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
12a60 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c  _USE_URI] symbol
12a70 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
12a80 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12a90 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54  PCACHE]] [[SQLIT
12aa0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
12ab0 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  HE]].** <dt>SQLI
12ac0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
12ad0 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46   and SQLITE_CONF
12ae0 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20  IG_GETPCACHE.** 
12af0 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f  <dd> These optio
12b00 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20  ns are obsolete 
12b10 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  and should not b
12b20 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f  e used by new co
12b30 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20  de..** They are 
12b40 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63  retained for bac
12b50 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
12b60 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77  lity but are now
12b70 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 6c   no-ops..** </dl
12b80 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
12b90 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
12ba0 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
12bb0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
12bc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
12bd0 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
12be0 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
12bf0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
12c00 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
12c10 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
12c20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
12c30 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
12c40 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
12c50 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
12c60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12c70 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
12c80 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
12c90 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
12ca0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
12cb0 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
12cc0 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  6  /* void*, int
12cd0 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
12ce0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
12cf0 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20  FIG_PAGECACHE   
12d00 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    7  /* void*, i
12d10 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
12d20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
12d30 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
12d40 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c      8  /* void*,
12d50 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20   int nByte, int 
12d60 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  min */.#define S
12d70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
12d80 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a  STATUS     9  /*
12d90 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66   boolean */.#def
12da0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
12db0 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31  G_MUTEX        1
12dc0 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  0  /* sqlite3_mu
12dd0 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
12de0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
12df0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20  ONFIG_GETMUTEX  
12e00 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65     11  /* sqlite
12e10 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
12e20 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c   */./* previousl
12e30 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  y SQLITE_CONFIG_
12e40 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68  CHUNKALLOC 12 wh
12e50 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65  ich is now unuse
12e60 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53  d. */ .#define S
12e70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
12e80 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a  KASIDE    13  /*
12e90 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
12ea0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
12eb0 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31  G_PCACHE       1
12ec0 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  4  /* no-op */.#
12ed0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
12ee0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20  NFIG_GETPCACHE  
12ef0 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    15  /* no-op *
12f00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
12f10 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20  _CONFIG_LOG     
12f20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e       16  /* xFun
12f30 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66  c, void* */.#def
12f40 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
12f50 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31  G_URI          1
12f60 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  7  /* int */.#de
12f70 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
12f80 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20  IG_PCACHE2      
12f90 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  18  /* sqlite3_p
12fa0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
12fb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
12fc0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
12fd0 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c  HE2   19  /* sql
12fe0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
12ff0 6f 64 73 32 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  ods2* */../*.** 
13000 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
13010 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f  se Connection Co
13020 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
13030 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
13040 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
13050 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
13060 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
13070 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
13080 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
13090 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
130a0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
130b0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
130c0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
130d0 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
130e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
130f0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
13100 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
13110 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
13120 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
13130 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
13140 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
13150 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
13160 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
13170 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
13180 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64   from [sqlite3_d
13190 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  b_config()] to m
131a0 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
131b0 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
131c0 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  .  ^The [sqlite3
131d0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
131e0 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
131f0 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
13200 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
13210 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
13220 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
13230 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13240 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
13250 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
13260 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
13270 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
13280 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
13290 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
132a0 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c  three additional
132b0 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
132c0 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a  determine the .*
132d0 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  * [lookaside mem
132e0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63  ory allocator] c
132f0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
13300 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
13310 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e  onnection]..** ^
13320 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
13330 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61  nt (the third pa
13340 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
13350 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
13360 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72   is a.** pointer
13370 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66   to a memory buf
13380 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c  fer to use for l
13390 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e  ookaside memory.
133a0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
133b0 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68  rgument after th
133c0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
133d0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62  G_LOOKASIDE verb
133e0 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20  .** may be NULL 
133f0 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51  in which case SQ
13400 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61  Lite will alloca
13410 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73  te the.** lookas
13420 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c  ide buffer itsel
13430 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  f using [sqlite3
13440 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65  _malloc()]. ^The
13450 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
13460 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
13470 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
13480 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20  e buffer slot.  
13490 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
134a0 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ent is the numbe
134b0 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20  r of.** slots.  
134c0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
134d0 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69  buffer in the fi
134e0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
134f0 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61  t be greater tha
13500 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f  n.** or equal to
13510 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20   the product of 
13520 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
13530 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20  hird arguments. 
13540 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d   The buffer.** m
13550 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
13560 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
13570 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73  dary.  ^If the s
13580 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
13590 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f  o.** SQLITE_DBCO
135a0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69  NFIG_LOOKASIDE i
135b0 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65  s not a multiple
135c0 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74   of 8, it is int
135d0 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64  ernally.** round
135e0 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e  ed down to the n
135f0 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74  ext smaller mult
13600 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68  iple of 8.  ^(Th
13610 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
13620 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  ry.** configurat
13630 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61  ion for a databa
13640 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61  se connection ca
13650 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65  n only be change
13660 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63  d when that.** c
13670 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74  onnection is not
13680 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67   currently using
13690 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
136a0 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77  y, or in other w
136b0 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65  ords.** when the
136c0 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22   "current value"
136d0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
136e0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74  [sqlite3_db_stat
136f0 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f  us](D,[SQLITE_CO
13700 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c  NFIG_LOOKASIDE],
13710 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a  ...) is zero..**
13720 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
13730 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
13740 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66  side memory conf
13750 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c  iguration when l
13760 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f  ookaside.** memo
13770 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61  ry is in use lea
13780 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72  ves the configur
13790 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20  ation unchanged 
137a0 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20  and returns .** 
137b0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e  [SQLITE_BUSY].)^
137c0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
137d0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
137e0 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e  ENABLE_FKEY</dt>
137f0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
13800 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
13810 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
13820 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65  le the enforceme
13830 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67  nt of.** [foreig
13840 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74  n key constraint
13850 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c  s].  There shoul
13860 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
13870 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
13880 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
13890 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
138a0 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
138b0 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f   disable FK enfo
138c0 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69  rcement,.** posi
138d0 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46  tive to enable F
138e0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72  K enforcement or
138f0 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
13900 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  ve FK enforcemen
13910 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20  t.** unchanged. 
13920 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
13930 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
13940 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
13950 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
13960 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
13970 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
13980 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d  ther FK enforcem
13990 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e  ent is off or on
139a0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
139b0 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
139c0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
139d0 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
139e0 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
139f0 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e  h case the FK en
13a00 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e  forcement settin
13a10 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
13a20 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
13a30 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
13a40 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
13a50 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  RIGGER</dt>.** <
13a60 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
13a70 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
13a80 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43  le or disable [C
13a90 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
13aa0 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68  triggers]..** Th
13ab0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
13ac0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
13ad0 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
13ae0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
13af0 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
13b00 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
13b10 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70  e triggers,.** p
13b20 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
13b30 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65  e triggers or ne
13b40 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
13b50 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68  the setting unch
13b60 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65  anged..** The se
13b70 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
13b80 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
13b90 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
13ba0 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
13bb0 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
13bc0 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72  icate whether tr
13bd0 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62  iggers are disab
13be0 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
13bf0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
13c00 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
13c10 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
13c20 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
13c30 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
13c40 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72  case the trigger
13c50 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
13c60 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
13c70 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
13c80 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
13c90 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
13ca0 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31  ASIDE       1001
13cb0 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69    /* void* int i
13cc0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
13cd0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
13ce0 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30  ABLE_FKEY     10
13cf0 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  02  /* int int* 
13d00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13d10 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
13d20 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20  E_TRIGGER  1003 
13d30 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
13d40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13d50 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
13d60 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73  ble Extended Res
13d70 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ult Codes.**.** 
13d80 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
13d90 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
13da0 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61  es() routine ena
13db0 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
13dc0 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65   the.** [extende
13dd0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
13de0 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74  feature of SQLit
13df0 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64  e. ^The extended
13e00 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73   result.** codes
13e10 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
13e20 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73   default for his
13e30 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62  torical compatib
13e40 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ility..*/.int sq
13e50 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
13e60 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69  esult_codes(sqli
13e70 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29  te3*, int onoff)
13e80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
13e90 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  F: Last Insert R
13ea0 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  owid.**.** ^Each
13eb0 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c   entry in an SQL
13ec0 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  ite table has a 
13ed0 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
13ee0 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
13ef0 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b  key called the [
13f00 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d  ROWID | "rowid"]
13f10 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20  . ^The rowid is 
13f20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
13f30 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
13f40 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
13f50 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
13f60 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
13f70 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
13f80 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
13f90 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
13fa0 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
13fb0 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20  mns. ^If.** the 
13fc0 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
13fd0 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45  mn of type [INTE
13fe0 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
13ff0 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
14000 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
14010 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f  alias for the ro
14020 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  wid..**.** ^This
14030 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
14040 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
14050 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a  the most recent.
14060 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
14070 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20  NSERT] into the 
14080 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68  database from th
14090 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
140a0 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  ection].** in th
140b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
140c0 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c 69 74 65  .  ^As of SQLite
140d0 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20   version 3.7.7, 
140e0 74 68 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  this routines.**
140f0 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61 73   records the las
14100 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 20 6f  t insert rowid o
14110 66 20 62 6f 74 68 20 6f 72 64 69 6e 61 72 79 20  f both ordinary 
14120 74 61 62 6c 65 73 20 61 6e 64 20 5b 76 69 72 74  tables and [virt
14130 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20  ual tables]..** 
14140 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75  ^If no successfu
14150 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68  l [INSERT]s.** h
14160 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
14170 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61  d on that databa
14180 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a  se connection, z
14190 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
141a0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b  .**.** ^(If an [
141b0 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77  INSERT] occurs w
141c0 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
141d0 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72  or within a [vir
141e0 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d  tual table].** m
141f0 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73  ethod, then this
14200 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65   routine will re
14210 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  turn the [rowid]
14220 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
14230 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20  .** row as long 
14240 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  as the trigger o
14250 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
14260 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e  method is runnin
14270 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74  g..** But once t
14280 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
14290 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
142a0 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c  od ends, the val
142b0 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20  ue returned .** 
142c0 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
142d0 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20  reverts to what 
142e0 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68  it was before th
142f0 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
14300 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65  tual.** table me
14310 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a  thod began.)^.**
14320 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d  .** ^An [INSERT]
14330 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20   that fails due 
14340 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  to a constraint 
14350 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74  violation is not
14360 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c   a.** successful
14370 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f   [INSERT] and do
14380 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
14390 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
143a0 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   by this.** rout
143b0 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45  ine.  ^Thus INSE
143c0 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45  RT OR FAIL, INSE
143d0 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e  RT OR IGNORE, IN
143e0 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b  SERT OR ROLLBACK
143f0 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20  ,.** and INSERT 
14400 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f  OR ABORT make no
14410 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
14420 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
14430 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
14440 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72  when their inser
14450 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57  tion fails.  ^(W
14460 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45  hen INSERT OR RE
14470 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74  PLACE.** encount
14480 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
14490 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
144a0 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
144b0 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
144c0 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
144d0 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
144e0 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
144f0 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
14500 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
14510 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
14520 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
14530 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
14540 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
14550 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a  is interface.)^.
14560 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
14570 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
14580 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53  routine, an [INS
14590 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72  ERT] is consider
145a0 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63  ed to.** be succ
145b0 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69  essful even if i
145c0 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c  t is subsequentl
145d0 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
145e0 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
145f0 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65  on is accessible
14600 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   to SQL statemen
14610 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c  ts via the.** [l
14620 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
14630 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
14640 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
14650 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72  arate thread per
14660 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53  forms a new [INS
14670 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65  ERT] on the same
14680 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
14690 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
146a0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
146b0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a  insert_rowid()].
146c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ** function is r
146d0 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
146e0 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
146f0 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c   insert [rowid],
14700 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c  .** then the val
14710 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ue returned by [
14720 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
14730 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a  ert_rowid()] is.
14740 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  ** unpredictable
14750 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65   and might not e
14760 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20  qual either the 
14770 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a  old or the new.*
14780 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  * last insert [r
14790 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65  owid]..*/.sqlite
147a0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
147b0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
147c0 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  d(sqlite3*);../*
147d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
147e0 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f  unt The Number O
147f0 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
14800 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
14810 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
14820 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62   number of datab
14830 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65  ase rows that we
14840 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72  re changed.** or
14850 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
14860 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  eted by the most
14870 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
14880 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
14890 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74  t.** on the [dat
148a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
148b0 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  ] specified by t
148c0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
148d0 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68  er..** ^(Only ch
148e0 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64  anges that are d
148f0 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65  irectly specifie
14900 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54  d by the [INSERT
14910 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20  ], [UPDATE],.** 
14920 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
14930 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65  ement are counte
14940 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68  d.  Auxiliary ch
14950 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a  anges caused by.
14960 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b  ** triggers or [
14970 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
14980 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75  ons] are not cou
14990 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a  nted.)^ Use the.
149a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  ** [sqlite3_tota
149b0 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e  l_changes()] fun
149c0 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68  ction to find th
149d0 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
149e0 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63  f changes.** inc
149f0 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63  luding changes c
14a00 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72  aused by trigger
14a10 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65  s and foreign ke
14a20 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  y actions..**.**
14a30 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76   ^Changes to a v
14a40 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d  iew that are sim
14a50 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e  ulated by an [IN
14a60 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
14a70 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75  ].** are not cou
14a80 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c  nted.  Only real
14a90 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61   table changes a
14aa0 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a  re counted..**.*
14ab0 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67  * ^(A "row chang
14ac0 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74  e" is a change t
14ad0 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f  o a single row o
14ae0 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65  f a single table
14af0 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e  .** caused by an
14b00 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c   INSERT, DELETE,
14b10 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65   or UPDATE state
14b20 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74  ment.  Rows that
14b30 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20  .** are changed 
14b40 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20  as side effects 
14b50 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e  of [REPLACE] con
14b60 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
14b70 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c  on,.** rollback,
14b80 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
14b90 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c  g, [DROP TABLE],
14ba0 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72   or by any other
14bb0 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64  .** mechanisms d
14bc0 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64  o not count as d
14bd0 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
14be0 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72  s.)^.**.** A "tr
14bf0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69  igger context" i
14c00 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65  s a scope of exe
14c10 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69  cution that begi
14c20 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77  ns and.** ends w
14c30 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f  ith the script o
14c40 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47  f a [CREATE TRIG
14c50 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20  GER | trigger]. 
14c60 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61  .** Most SQL sta
14c70 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65  tements are.** e
14c80 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65  valuated outside
14c90 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e   of any trigger.
14ca0 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74    This is the "t
14cb0 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69  op level".** tri
14cc0 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49  gger context.  I
14cd0 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65  f a trigger fire
14ce0 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  s from the top l
14cf0 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74  evel, a.** new t
14d00 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69  rigger context i
14d10 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68  s entered for th
14d20 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68  e duration of th
14d30 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65  at one.** trigge
14d40 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20  r.  Subtriggers 
14d50 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78  create subcontex
14d60 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72  ts for their dur
14d70 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  ation..**.** ^Ca
14d80 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
14d90 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  xec()] or [sqlit
14da0 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72  e3_step()] recur
14db0 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e  sively does.** n
14dc0 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20  ot create a new 
14dd0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
14de0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
14df0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
14e00 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65  e number of dire
14e10 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69  ct row changes i
14e20 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65  n the.** most re
14e30 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
14e40 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73  ATE, or DELETE s
14e50 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
14e60 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67  the same.** trig
14e70 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
14e80 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63  ** ^Thus, when c
14e90 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74  alled from the t
14ea0 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66  op level, this f
14eb0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
14ec0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
14ed0 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
14ee0 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
14ef0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
14f00 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c  ELETE.** that al
14f10 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74  so occurred at t
14f20 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e  he top level.  ^
14f30 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79  (Within the body
14f40 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a   of a trigger,.*
14f50 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  * the sqlite3_ch
14f60 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63  anges() interfac
14f70 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
14f80 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
14f90 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73  er of.** changes
14fa0 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
14fb0 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
14fc0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
14fd0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
14fe0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
14ff0 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61  e body of the sa
15000 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48  me trigger..** H
15010 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62  owever, the numb
15020 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  er returned does
15030 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
15040 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62  nges.** caused b
15050 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69  y subtriggers si
15060 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74  nce those have t
15070 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74  heir own context
15080 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
15090 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
150a0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
150b0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
150c0 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
150d0 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
150e0 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
150f0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
15100 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
15110 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
15120 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
15130 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
15140 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
15150 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
15160 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
15170 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
15180 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72  urned.** is unpr
15190 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
151a0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
151b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61  .int sqlite3_cha
151c0 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
151d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
151e0 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66   Total Number Of
151f0 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
15200 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
15210 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
15220 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68  number of row ch
15230 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
15240 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50  [INSERT],.** [UP
15250 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45  DATE] or [DELETE
15260 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e  ] statements sin
15270 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ce the [database
15280 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73   connection] was
15290 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68   opened..** ^(Th
152a0 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64  e count returned
152b0 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61   by sqlite3_tota
152c0 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c  l_changes() incl
152d0 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73  udes all changes
152e0 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52  .** from all [CR
152f0 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
15300 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73  rigger] contexts
15310 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64   and changes mad
15320 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  e by.** [foreign
15330 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48   key actions]. H
15340 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63  owever,.** the c
15350 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
15360 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73  clude changes us
15370 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
15380 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
15390 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c  aints,.** do rol
153a0 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20  lbacks or ABORT 
153b0 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b  processing, or [
153c0 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63  DROP TABLE] proc
153d0 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20  essing.  The.** 
153e0 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69  count does not i
153f0 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76  nclude rows of v
15400 69 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61  iews that fire a
15410 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  n [INSTEAD OF tr
15420 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67  igger],.** thoug
15430 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44  h if the INSTEAD
15440 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65   OF trigger make
15450 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73  s changes of its
15460 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e   own, those chan
15470 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e  ges .** are coun
15480 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73  ted.)^.** ^The s
15490 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
154a0 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  nges() function 
154b0 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67  counts the chang
154c0 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a  es as soon as.**
154d0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
154e0 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69  hat makes them i
154f0 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65  s completed (whe
15500 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
15510 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73  handle.** is pas
15520 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  sed to [sqlite3_
15530 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
15540 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
15550 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
15560 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
15570 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
15580 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
15590 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
155a0 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74  a], and the [tot
155b0 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c  al_changes() SQL
155c0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
155d0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
155e0 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
155f0 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
15600 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15610 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
15620 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
15630 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
15640 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
15650 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
15660 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
15670 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
15680 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
15690 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
156a0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
156b0 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
156c0 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
156d0 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a  ning Query.**.**
156e0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
156f0 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69  causes any pendi
15700 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  ng database oper
15710 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61  ation to abort a
15720 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20  nd.** return at 
15730 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70  its earliest opp
15740 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72  ortunity. This r
15750 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61  outine is typica
15760 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e  lly.** called in
15770 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75   response to a u
15780 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20  ser action such 
15790 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e  as pressing "Can
157a0 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d  cel".** or Ctrl-
157b0 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72  C where the user
157c0 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75   wants a long qu
157d0 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ery operation to
157e0 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61   halt.** immedia
157f0 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  tely..**.** ^It 
15800 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
15810 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
15820 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
15830 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
15840 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
15850 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
15860 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
15870 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
15880 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
15890 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
158a0 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
158b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
158c0 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
158d0 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
158e0 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
158f0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
15900 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  eturns..**.** ^I
15910 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  f an SQL operati
15920 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c  on is very nearl
15930 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68  y finished at th
15940 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73  e time when.** s
15950 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
15960 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  () is called, th
15970 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20  en it might not 
15980 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e  have an opportun
15990 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74  ity.** to be int
159a0 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67  errupted and mig
159b0 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63  ht continue to c
159c0 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ompletion..**.**
159d0 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69   ^An SQL operati
159e0 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
159f0 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
15a00 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
15a10 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  RUPT]..** ^If th
15a20 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51  e interrupted SQ
15a30 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  L operation is a
15a40 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
15a50 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
15a60 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e  hat is inside an
15a70 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
15a80 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ction, then the 
15a90 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69  entire transacti
15aa0 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f  on.** will be ro
15ab0 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
15ac0 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  tically..**.** ^
15ad0 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  The sqlite3_inte
15ae0 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73  rrupt(D) call is
15af0 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c   in effect until
15b00 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72   all currently r
15b10 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
15b20 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74  atements on [dat
15b30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15b40 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  ] D complete.  ^
15b50 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74  Any new SQL stat
15b60 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
15b70 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
15b80 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
15b90 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e  errupt() call an
15ba0 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a  d before the .**
15bb0 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
15bc0 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f  nts reaches zero
15bd0 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64   are interrupted
15be0 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20   as if they had 
15bf0 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  been.** running 
15c00 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c  prior to the sql
15c10 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
15c20 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c   call.  ^New SQL
15c30 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
15c40 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
15c50 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e  after the runnin
15c60 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e  g statement coun
15c70 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  t reaches zero a
15c80 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74  re.** not effect
15c90 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
15ca0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a  3_interrupt()..*
15cb0 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  * ^A call to sql
15cc0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
15cd0 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68  ) that occurs wh
15ce0 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  en there are no 
15cf0 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
15d00 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e  tatements is a n
15d10 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20  o-op and has no 
15d20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74  effect on SQL st
15d30 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
15d40 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
15d50 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
15d60 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
15d70 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  returns..**.** I
15d80 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
15d90 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
15da0 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
15db0 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20  interrupt()].** 
15dc0 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
15dd0 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20  bad things will 
15de0 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a  likely happen..*
15df0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69  /.void sqlite3_i
15e00 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33  nterrupt(sqlite3
15e10 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
15e20 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
15e30 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
15e40 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a  nt Is Complete.*
15e50 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
15e60 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64  nes are useful d
15e70 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69  uring command-li
15e80 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
15e90 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
15ea0 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
15eb0 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20  d text seems to 
15ec0 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20  form a complete 
15ed0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  SQL statement or
15ee0 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61  .** if additiona
15ef0 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65  l input is neede
15f00 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67  d before sending
15f10 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a   the text into.*
15f20 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72  * SQLite for par
15f30 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f  sing.  ^These ro
15f40 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20  utines return 1 
15f50 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  if the input str
15f60 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74  ing.** appears t
15f70 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20  o be a complete 
15f80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
15f90 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ^A statement is 
15fa0 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20  judged to be.** 
15fb0 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65  complete if it e
15fc0 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63  nds with a semic
15fd0 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69  olon token and i
15fe0 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f  s not a prefix o
15ff0 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d  f a.** well-form
16000 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45  ed CREATE TRIGGE
16010 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53  R statement.  ^S
16020 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61  emicolons that a
16030 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68  re embedded with
16040 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74  in.** string lit
16050 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20  erals or quoted 
16060 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73  identifier names
16070 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65   or comments are
16080 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64   not.** independ
16090 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79  ent tokens (they
160a0 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65   are part of the
160b0 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20   token in which 
160c0 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65  they are.** embe
160d0 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64  dded) and thus d
160e0 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61  o not count as a
160f0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69   statement termi
16100 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70  nator.  ^Whitesp
16110 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65  ace.** and comme
16120 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  nts that follow 
16130 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f  the final semico
16140 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e  lon are ignored.
16150 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
16160 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20  utines return 0 
16170 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
16180 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20   is incomplete. 
16190 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79   ^If a.** memory
161a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
161b0 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e  s, then SQLITE_N
161c0 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64  OMEM is returned
161d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
161e0 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70  outines do not p
161f0 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61  arse the SQL sta
16200 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20  tements thus.** 
16210 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20  will not detect 
16220 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e  syntactically in
16230 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a  correct SQL..**.
16240 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68  ** ^(If SQLite h
16250 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74  as not been init
16260 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73  ialized using [s
16270 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
16280 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74  e()] prior .** t
16290 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74  o invoking sqlit
162a0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
162b0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69  then sqlite3_ini
162c0 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
162d0 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  oked.** automati
162e0 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
162f0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20  _complete16().  
16300 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69  If that initiali
16310 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a  zation fails,.**
16320 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
16330 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
16340 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
16350 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72   will be non-zer
16360 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  o.** regardless 
16370 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
16380 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20  t the input SQL 
16390 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a  is complete.)^.*
163a0 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
163b0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
163c0 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61  ete()] must be a
163d0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
163e0 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67  .** UTF-8 string
163f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ..**.** The inpu
16400 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
16410 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74  mplete16()] must
16420 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
16430 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
16440 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
16450 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a   byte order..*/.
16460 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
16470 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
16480 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  *sql);.int sqlit
16490 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
164a0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
164b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
164c0 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
164d0 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
164e0 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
164f0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
16500 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c  utine sets a cal
16510 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74  lback function t
16520 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76  hat might be inv
16530 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a  oked whenever.**
16540 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
16550 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61  ade to open a da
16560 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61  tabase table tha
16570 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  t another thread
16580 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68  .** or process h
16590 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a  as locked..**.**
165a0 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
165b0 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20  llback is NULL, 
165c0 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  then [SQLITE_BUS
165d0 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
165e0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
165f0 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
16600 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63  diately upon enc
16610 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f  ountering the lo
16620 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73  ck.  ^If the bus
16630 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  y callback.** is
16640 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
16650 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67  the callback mig
16660 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
16670 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  th two arguments
16680 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
16690 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
166a0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
166b0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
166c0 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
166d0 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
166e0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
166f0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
16700 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73  ndler().  ^The s
16710 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
16720 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  o.** the busy ha
16730 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
16740 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
16750 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
16760 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
16770 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
16780 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67  for this locking
16790 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
167a0 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63  .** busy callbac
167b0 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65  k returns 0, the
167c0 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20  n no additional 
167d0 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64  attempts are mad
167e0 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74  e to.** access t
167f0 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
16800 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
16810 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
16820 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72  LOCKED] is retur
16830 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ned..** ^If the 
16840 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
16850 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
16860 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a  another attempt.
16870 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  ** is made to op
16880 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
16890 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
168a0 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74  the cycle repeat
168b0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65  s..**.** The pre
168c0 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20  sence of a busy 
168d0 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74  handler does not
168e0 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
168f0 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  it will be invok
16900 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65  ed.** when there
16910 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74   is lock content
16920 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ion. ^If SQLite 
16930 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20  determines that 
16940 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
16950 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75  y.** handler cou
16960 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64  ld result in a d
16970 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c  eadlock, it will
16980 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65   go ahead and re
16990 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
169a0 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  Y].** or [SQLITE
169b0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20  _IOERR_BLOCKED] 
169c0 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b  instead of invok
169d0 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e  ing the busy han
169e0 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65  dler..** Conside
169f0 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65  r a scenario whe
16a00 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69  re one process i
16a10 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64  s holding a read
16a20 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74   lock that.** it
16a30 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72   is trying to pr
16a40 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72  omote to a reser
16a50 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20  ved lock and.** 
16a60 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  a second process
16a70 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
16a80 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74  served lock that
16a90 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a   it is trying.**
16aa0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
16ab0 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b  n exclusive lock
16ac0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f  .  The first pro
16ad0 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63  cess cannot proc
16ae0 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69  eed.** because i
16af0 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
16b00 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
16b10 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
16b20 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63  s cannot.** proc
16b30 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69  eed because it i
16b40 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
16b50 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68   first.  If both
16b60 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e   processes.** in
16b70 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61  voke the busy ha
16b80 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20  ndlers, neither 
16b90 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72  will make any pr
16ba0 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f  ogress.  Therefo
16bb0 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65  re,.** SQLite re
16bc0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
16bd0 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  SY] for the firs
16be0 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e  t process, hopin
16bf0 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77  g that this.** w
16c00 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66  ill induce the f
16c10 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20  irst process to 
16c20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64  release its read
16c30 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a   lock and allow.
16c40 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  ** the second pr
16c50 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64  ocess to proceed
16c60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
16c70 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61  ault busy callba
16c80 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ck is NULL..**.*
16c90 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42  * ^The [SQLITE_B
16ca0 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f  USY] error is co
16cb0 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49  nverted to [SQLI
16cc0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
16cd0 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  ].** when SQLite
16ce0 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c   is in the middl
16cf0 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61  e of a large tra
16d00 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61  nsaction where a
16d10 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65  ll the.** change
16d20 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69  s will not fit i
16d30 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72  nto the in-memor
16d40 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65  y cache.  SQLite
16d50 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79   will.** already
16d60 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44   hold a RESERVED
16d70 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74   lock on the dat
16d80 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20  abase file, but 
16d90 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70  it needs.** to p
16da0 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b  romote this lock
16db0 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f   to EXCLUSIVE so
16dc0 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69   that it can spi
16dd0 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65  ll cache.** page
16de0 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  s into the datab
16df0 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74  ase file without
16e00 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72   harm to concurr
16e10 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20  ent.** readers. 
16e20 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c   ^If it is unabl
16e30 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65  e to promote the
16e40 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20   lock, then the 
16e50 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63  in-memory.** cac
16e60 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20  he will be left 
16e70 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65  in an inconsiste
16e80 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20  nt state and so 
16e90 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64  the error.** cod
16ea0 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72  e is promoted fr
16eb0 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c  om the relativel
16ec0 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45  y benign [SQLITE
16ed0 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65  _BUSY] to.** the
16ee0 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51   more severe [SQ
16ef0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
16f00 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f  ED].  ^This erro
16f10 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e  r code promotion
16f20 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75  .** forces an au
16f30 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b  tomatic rollback
16f40 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e   of the changes.
16f50 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20    See the.** <a 
16f60 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77  href="/cvstrac/w
16f70 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e  iki?p=Corruption
16f80 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
16f90 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69  or">.** Corrupti
16fa0 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
16fb0 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61  rror</a> wiki pa
16fc0 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73  ge for a discuss
16fd0 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68  ion of why.** th
16fe0 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e  is is important.
16ff0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
17000 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
17010 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
17020 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63   defined for eac
17030 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
17040 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74  onnection].  Set
17050 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20  ting a new busy 
17060 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61  handler clears a
17070 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ny.** previously
17080 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20   set handler.)^ 
17090 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c   ^Note that call
170a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
170b0 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20  y_timeout()].** 
170c0 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72  will also set or
170d0 20 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20   clear the busy 
170e0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  handler..**.** T
170f0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
17100 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65   should not take
17110 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69   any actions whi
17120 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a  ch modify the.**
17130 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17140 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
17150 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
17160 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63  er.  Any such ac
17170 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20  tions.** result 
17180 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
17190 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20  avior..** .** A 
171a0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73  busy handler mus
171b0 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
171c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
171d0 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61  ion.** or [prepa
171e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
171f0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
17200 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f  busy handler..*/
17210 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
17220 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  y_handler(sqlite
17230 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
17240 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  ,int), void*);..
17250 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17260 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
17270 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  ut.**.** ^This r
17280 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
17290 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
172a0 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
172b0 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
172c0 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
172d0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
172e0 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
172f0 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20  s locked.  ^The 
17300 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20  handler.** will 
17310 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74  sleep multiple t
17320 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65  imes until at le
17330 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
17340 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
17350 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75  g.** have accumu
17360 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61  lated.  ^After a
17370 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
17380 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
17390 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61  eping,.** the ha
173a0 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20  ndler returns 0 
173b0 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71  which causes [sq
173c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f  lite3_step()] to
173d0 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
173e0 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
173f0 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
17400 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  D]..**.** ^Calli
17410 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
17420 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74  with an argument
17430 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
17440 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74  ual to zero.** t
17450 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73  urns off all bus
17460 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a  y handlers..**.*
17470 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
17480 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
17490 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
174a0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
174b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
174c0 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69  tion] any any gi
174d0 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
174e0 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
174f0 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
17500 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
17510 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
17520 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
17530 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
17540 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
17550 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
17560 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f  is cleared.)^.*/
17570 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
17580 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
17590 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
175a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
175b0 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
175c0 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
175d0 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69  ueries.**.** Thi
175e0 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e  s is a legacy in
175f0 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20  terface that is 
17600 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61  preserved for ba
17610 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
17620 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66  ility..** Use of
17630 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
17640 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64  is not recommend
17650 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  ed..**.** Defini
17660 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
17670 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
17680 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
17690 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
176a0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
176b0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
176c0 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
176d0 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
176e0 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
176f0 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
17700 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
17710 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
17720 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
17730 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
17740 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
17750 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
17760 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
17770 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
17780 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
17790 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
177a0 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
177b0 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
177c0 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
177d0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
177e0 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
177f0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
17800 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
17810 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
17820 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
17830 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
17840 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
17850 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
17860 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
17870 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
17880 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
17890 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
178a0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
178b0 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
178c0 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
178d0 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
178e0 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
178f0 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
17900 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
17910 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
17920 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
17930 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
17940 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
17950 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
17960 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
17970 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
17980 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
17990 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
179a0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
179b0 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
179c0 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
179d0 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
179e0 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
179f0 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
17a00 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
17a10 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
17a20 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
17a30 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
17a40 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
17a50 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
17a60 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
17a70 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
17a80 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20  ()]..**.** ^(As 
17a90 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
17aa0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
17ab0 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
17ac0 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
17ad0 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
17ae0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
17af0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
17b00 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
17b10 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
17b20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
17b30 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
17b40 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
17b50 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
17b60 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
17b70 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
17b80 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
17b90 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
17ba0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
17bb0 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
17bc0 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
17bd0 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
17be0 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
17bf0 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
17c00 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
17c10 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
17c20 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
17c30 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
17c40 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
17c50 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
17c60 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
17c70 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
17c80 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
17c90 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
17ca0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
17cb0 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
17cc0 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
17cd0 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
17ce0 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
17cf0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
17d00 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
17d10 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
17d20 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
17d30 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
17d40 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
17d50 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
17d60 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
17d70 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
17d80 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
17d90 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
17da0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
17db0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
17dc0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
17dd0 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
17de0 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
17df0 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
17e00 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
17e10 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
17e20 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
17e30 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
17e40 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
17e50 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72   and returns a r
17e60 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
17e70 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
17e80 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
17e90 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
17ea0 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63  After the applic
17eb0 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ation has finish
17ec0 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75  ed with the resu
17ed0 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  lt from sqlite3_
17ee0 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20  get_table(),.** 
17ef0 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65  it must pass the
17f00 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f   result table po
17f10 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
17f20 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
17f30 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c   order to.** rel
17f40 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
17f50 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65  that was malloce
17f60 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  d.  Because of t
17f70 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73  he way the.** [s
17f80 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
17f90 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20   happens within 
17fa0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
17fb0 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  e(), the calling
17fc0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
17fd0 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c  t not try to cal
17fe0 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  l [sqlite3_free(
17ff0 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e  )] directly.  On
18000 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ly.** [sqlite3_f
18010 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  ree_table()] is 
18020 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20  able to release 
18030 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65  the memory prope
18040 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a  rly and safely..
18050 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
18060 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e  3_get_table() in
18070 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
18080 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70  mented as a wrap
18090 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
180a0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20  qlite3_exec()]. 
180b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
180c0 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65  _table() routine
180d0 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61   does not have a
180e0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20  ccess.** to any 
180f0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74  internal data st
18100 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69  ructures of SQLi
18110 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c  te.  It uses onl
18120 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20  y the public.** 
18130 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65  interface define
18140 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f  d here.  As a co
18150 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72  nsequence, error
18160 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20  s that occur in 
18170 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c  the.** wrapper l
18180 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20  ayer outside of 
18190 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71  the internal [sq
181a0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61  lite3_exec()] ca
181b0 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  ll are not.** re
181c0 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65  flected in subse
181d0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
181e0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
181f0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
18200 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a  3_errmsg()]..*/.
18210 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
18220 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  table(.  sqlite3
18230 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
18240 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
18250 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
18260 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a  ar *zSql,     /*
18270 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
18280 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ated */.  char *
18290 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20  **pazResult,    
182a0 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68  /* Results of th
182b0 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74  e query */.  int
182c0 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20   *pnRow,        
182d0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
182e0 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74  result rows writ
182f0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e  ten here */.  in
18300 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20  t *pnColumn,    
18310 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
18320 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20   result columns 
18330 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
18340 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73    char **pzErrms
18350 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72  g       /* Error
18360 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
18370 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c  e */.);.void sql
18380 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
18390 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a  char **result);.
183a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
183b0 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e   Formatted Strin
183c0 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74  g Printing Funct
183d0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
183e0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
183f0 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65  rk-alikes of the
18400 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69   "printf()" fami
18410 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ly of functions.
18420 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ** from the stan
18430 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
18440 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
18450 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
18460 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
18470 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69  f() routines wri
18480 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75  te their.** resu
18490 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  lts into memory 
184a0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
184b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
184c0 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73  ..** The strings
184d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
184e0 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20  se two routines 
184f0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c  should be.** rel
18500 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eased by [sqlite
18510 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74  3_free()].  ^Bot
18520 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  h routines retur
18530 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
18540 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  ter if [sqlite3_
18550 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61  malloc()] is una
18560 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
18570 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79  enough.** memory
18580 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
18590 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a  ulting string..*
185a0 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
185b0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
185c0 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
185d0 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
185e0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
185f0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
18600 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
18610 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
18620 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
18630 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
18640 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
18650 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
18660 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
18670 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
18680 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
18690 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
186a0 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
186b0 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
186c0 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68  nprintf().)^  Th
186d0 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
186e0 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
186f0 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
18700 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
18710 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
18720 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
18730 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74  .  ^(Note also t
18740 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  hat sqlite3_snpr
18750 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e  intf().** return
18760 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
18770 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61  ts buffer instea
18780 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  d of the number 
18790 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  of.** characters
187a0 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65   actually writte
187b0 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  n into the buffe
187c0 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74  r.)^  We admit t
187d0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
187e0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
187f0 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
18800 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
18810 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
18820 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
18830 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
18840 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
18850 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
18860 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
18870 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
18880 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f  ty..**.** ^As lo
18890 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
188a0 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
188b0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
188c0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
188d0 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
188e0 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
188f0 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
18900 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69  inated.  ^The fi
18910 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
18920 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
18930 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
18940 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
18950 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
18960 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
18970 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
18980 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
18990 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
189a0 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
189b0 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
189c0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
189d0 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
189e0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76  ) routine is a v
189f0 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f  arargs version o
18a00 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
18a10 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tf()..**.** Thes
18a20 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
18a30 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
18a40 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
18a50 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
18a60 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
18a70 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
18a80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
18a90 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
18aa0 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72  ual printf() for
18ab0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
18ac0 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
18ad0 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
18ae0 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
18af0 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
18b00 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  s..**.** ^(The %
18b10 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  q option works l
18b20 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69  ike %s in that i
18b30 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20  t substitutes a 
18b40 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
18b50 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68  * string from th
18b60 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e  e argument list.
18b70 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f    But %q also do
18b80 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27  ubles every '\''
18b90 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25   character..** %
18ba0 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f  q is designed fo
18bb0 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73  r use inside a s
18bc0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e  tring literal.)^
18bd0 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61    By doubling ea
18be0 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61  ch '\''.** chara
18bf0 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20  cter it escapes 
18c00 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61  that character a
18c10 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20  nd allows it to 
18c20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  be inserted into
18c30 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a  .** the string..
18c40 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
18c50 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74  e, assume the st
18c60 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54  ring variable zT
18c70 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78  ext contains tex
18c80 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
18c90 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
18ca0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
18cb0 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20  zText = "It's a 
18cc0 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20  happy day!";.** 
18cd0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
18ce0 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61  te>.**.** One ca
18cf0 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20  n use this text 
18d00 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
18d10 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ent as follows:.
18d20 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
18d30 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
18d40 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
18d50 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
18d60 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
18d70 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74  ES('%q')", zText
18d80 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
18d90 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
18da0 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
18db0 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
18dc0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
18dd0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63  quote>.**.** Bec
18de0 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d  ause the %q form
18df0 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65  at string is use
18e00 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72  d, the '\'' char
18e10 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a  acter in zText.*
18e20 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64  * is escaped and
18e30 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74   the SQL generat
18e40 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ed is as follows
18e50 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
18e60 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
18e70 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
18e80 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61   VALUES('It''s a
18e90 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a   happy day!').**
18ea0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
18eb0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
18ec0 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64  is correct.  Had
18ed0 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74   we used %s inst
18ee0 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67  ead of %q, the g
18ef0 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20  enerated SQL.** 
18f00 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65  would have looke
18f10 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  d like this:.**.
18f20 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
18f30 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
18f40 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
18f50 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79  ES('It's a happy
18f60 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72   day!');.** </pr
18f70 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
18f80 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e  **.** This secon
18f90 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20  d example is an 
18fa0 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72  SQL syntax error
18fb0 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20  .  As a general 
18fc0 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a  rule you should.
18fd0 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71  ** always use %q
18fe0 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77   instead of %s w
18ff0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65  hen inserting te
19000 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67  xt into a string
19010 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20   literal..**.** 
19020 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  ^(The %Q option 
19030 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
19040 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
19050 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
19060 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
19070 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
19080 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69  al string.  Addi
19090 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65  tionally, if the
190a0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
190b0 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69  e.** argument li
190c0 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  st is a NULL poi
190d0 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74  nter, %Q substit
190e0 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e  utes the text "N
190f0 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a  ULL" (without.**
19100 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e   single quotes).
19110 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d  )^  So, for exam
19120 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73  ple, one could s
19130 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ay:.**.** <block
19140 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
19150 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
19160 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
19170 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
19180 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65  VALUES(%Q)", zTe
19190 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
191a0 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
191b0 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
191c0 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
191d0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
191e0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
191f0 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69  he code above wi
19200 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72  ll render a corr
19210 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ect SQL statemen
19220 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a  t in the zSQL.**
19230 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69   variable even i
19240 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69  f the zText vari
19250 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70  able is a NULL p
19260 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ointer..**.** ^(
19270 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74  The "%z" formatt
19280 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73  ing option works
19290 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77   like "%s" but w
192a0 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
192b0 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
192c0 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
192d0 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
192e0 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
192f0 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
19300 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
19310 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
19320 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72  tring.)^.*/.char
19330 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   *sqlite3_mprint
19340 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e  f(const char*,..
19350 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
19360 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
19370 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
19380 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
19390 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
193a0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
193b0 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
193c0 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e  te3_vsnprintf(in
193d0 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
193e0 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a  ar*, va_list);..
193f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19400 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
19410 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a  n Subsystem.**.*
19420 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
19430 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72  e uses these thr
19440 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
19450 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
19460 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
19470 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
19480 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
19490 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
194a0 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
194b0 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
194c0 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
194d0 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
194e0 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
194f0 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
19500 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
19510 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
19520 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
19530 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
19540 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
19550 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
19560 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
19570 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
19580 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
19590 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
195a0 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
195b0 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  r..** ^If sqlite
195c0 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
195d0 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
195e0 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
195f0 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
19600 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
19610 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61  ter.  ^If the pa
19620 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
19630 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
19640 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
19650 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
19660 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
19670 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
19680 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  nter..**.** ^Cal
19690 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
196a0 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
196b0 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
196c0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
196d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
196e0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
196f0 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
19700 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
19710 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
19720 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
19730 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
19740 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
19750 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
19760 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
19770 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
19780 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
19790 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
197a0 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
197b0 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
197c0 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
197d0 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
197e0 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
197f0 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
19800 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
19810 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
19820 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
19830 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
19840 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
19850 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
19860 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
19870 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
19880 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
19890 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
198a0 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
198b0 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
198c0 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
198d0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
198e0 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
198f0 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
19900 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
19910 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
19920 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
19930 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e  te3_realloc() in
19940 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
19950 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
19960 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
19970 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74  ocation to be at
19980 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20   least N bytes, 
19990 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
199a0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
199b0 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20  er.  The memory 
199c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
199d0 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20   resized is the 
199e0 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
199f0 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66  er.)^ ^ If the f
19a00 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
19a10 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
19a20 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  c().** is a NULL
19a30 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
19a40 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
19a50 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
19a60 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
19a70 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20  lloc(N) where N 
19a80 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  is the second pa
19a90 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
19aa0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
19ab0 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
19ac0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
19ad0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69  ite3_realloc() i
19ae0 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67  s zero or.** neg
19af0 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62  ative then the b
19b00 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74  ehavior is exact
19b10 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63  ly the same as c
19b20 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
19b30 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20  3_free(P) where 
19b40 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  P is the first p
19b50 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
19b60 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
19b70 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  * ^sqlite3_reall
19b80 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  oc() returns a p
19b90 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
19ba0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
19bb0 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
19bc0 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
19bd0 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65  NULL if sufficie
19be0 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61  nt memory is una
19bf0 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66  vailable..** ^If
19c00 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
19c10 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
19c20 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
19c30 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
19c40 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
19c50 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
19c60 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
19c70 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
19c80 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
19c90 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
19ca0 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
19cb0 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
19cc0 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
19cd0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
19ce0 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  rns NULL, then t
19cf0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
19d00 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72  ion.** is not fr
19d10 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
19d20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
19d30 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
19d40 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  c() and sqlite3_
19d50 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
19d60 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74  always aligned t
19d70 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20  o at least an 8 
19d80 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f  byte boundary, o
19d90 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65  r to a.** 4 byte
19da0 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65   boundary if the
19db0 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f   [SQLITE_4_BYTE_
19dc0 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20  ALIGNED_MALLOC] 
19dd0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
19de0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a  option is used..
19df0 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20  **.** In SQLite 
19e00 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e  version 3.5.0 an
19e10 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20  d 3.5.1, it was 
19e20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69  possible to defi
19e30 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45  ne.** the SQLITE
19e40 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c  _OMIT_MEMORY_ALL
19e50 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f  OCATION which wo
19e60 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75  uld cause the bu
19e70 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  ilt-in.** implem
19e80 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73  entation of thes
19e90 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  e routines to be
19ea0 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20   omitted.  That 
19eb0 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
19ec0 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69   no longer provi
19ed0 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74  ded.  Only built
19ee0 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
19ef0 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65  ators can be use
19f00 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e  d..**.** The Win
19f10 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63  dows OS interfac
19f20 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a  e layer calls.**
19f30 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
19f40 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
19f50 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
19f60 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
19f70 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
19f80 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
19f90 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
19fa0 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
19fb0 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
19fc0 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
19fd0 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
19fe0 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
19ff0 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
1a000 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61  ocation errors a
1a010 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74  re detected, but
1a020 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70  .** they are rep
1a030 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53  orted back as [S
1a040 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
1a050 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
1a060 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e  ERR] rather than
1a070 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
1a080 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  .**.** The point
1a090 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
1a0a0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1a0b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1a0c0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  alloc()].** must
1a0d0 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20   be either NULL 
1a0e0 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73  or else pointers
1a0f0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
1a100 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61   prior.** invoca
1a110 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
1a120 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
1a130 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1a140 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e  ] that have.** n
1a150 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65  ot yet been rele
1a160 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ased..**.** The 
1a170 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
1a180 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69   not read or wri
1a190 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a  te any part of.*
1a1a0 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  * a block of mem
1a1b0 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73  ory after it has
1a1c0 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75   been released u
1a1d0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
1a1e0 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c  _free()] or [sql
1a1f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e  ite3_realloc()].
1a200 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
1a210 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76  3_malloc(int);.v
1a220 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
1a230 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
1a240 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
1a250 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  ree(void*);../*.
1a260 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
1a270 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74  ory Allocator St
1a280 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53  atistics.**.** S
1a290 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
1a2a0 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
1a2b0 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
1a2c0 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
1a2d0 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
1a2e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
1a2f0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
1a300 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1a310 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
1a320 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
1a330 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
1a340 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
1a350 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
1a360 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
1a370 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75  mory_used()] rou
1a380 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
1a390 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
1a3a0 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75  .** of memory cu
1a3b0 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64  rrently outstand
1a3c0 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75  ing (malloced bu
1a3d0 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a  t not freed)..**
1a3e0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1a3f0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1a400 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1a410 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  ns the maximum.*
1a420 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69  * value of [sqli
1a430 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1a440 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67  )] since the hig
1a450 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
1a460 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20  was last reset. 
1a470 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
1a480 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1a490 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1a4a0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1a4b0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1a4c0 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79  r()] include any
1a4d0 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64   overhead.** add
1a4e0 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20  ed by SQLite in 
1a4f0 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  its implementati
1a500 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
1a510 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74  alloc()],.** but
1a520 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64   not overhead ad
1a530 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75  ded by the any u
1a540 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d  nderlying system
1a550 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74   library.** rout
1a560 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74  ines that [sqlit
1a570 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79  e3_malloc()] may
1a580 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   call..**.** ^Th
1a590 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61  e memory high-wa
1a5a0 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65  ter mark is rese
1a5b0 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74  t to the current
1a5c0 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71   value of.** [sq
1a5d0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1a5e0 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  d()] if and only
1a5f0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1a600 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
1a610 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1a620 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e  r()] is true.  ^
1a630 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
1a640 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
1a650 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1a660 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69  er(1)] is the hi
1a670 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1a680 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65   prior to the re
1a690 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  set..*/.sqlite3_
1a6a0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
1a6b0 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b  mory_used(void);
1a6c0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
1a6d0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1a6e0 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65  ghwater(int rese
1a6f0 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  tFlag);../*.** C
1a700 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d  API3REF: Pseudo-
1a710 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65  Random Number Ge
1a720 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51  nerator.**.** SQ
1a730 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20  Lite contains a 
1a740 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65  high-quality pse
1a750 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65  udo-random numbe
1a760 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e  r generator (PRN
1a770 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65  G) used to.** se
1a780 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57  lect random [ROW
1a790 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65  ID | ROWIDs] whe
1a7a0 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20  n inserting new 
1a7b0 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74  records into a t
1a7c0 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72  able that.** alr
1a7d0 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61  eady uses the la
1a7e0 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b  rgest possible [
1a7f0 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e  ROWID].  The PRN
1a800 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66  G is also used f
1a810 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d  or.** the build-
1a820 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20  in random() and 
1a830 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c  randomblob() SQL
1a840 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69   functions.  Thi
1a850 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
1a860 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  ws.** applicatio
1a870 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ns to access the
1a880 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f   same PRNG for o
1a890 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a  ther purposes..*
1a8a0 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  *.** ^A call to 
1a8b0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  this routine sto
1a8c0 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72  res N bytes of r
1a8d0 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62  andomness into b
1a8e0 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e  uffer P..**.** ^
1a8f0 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
1a900 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69  his routine is i
1a910 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69  nvoked (either i
1a920 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a  nternally or by.
1a930 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
1a940 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20  on) the PRNG is 
1a950 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e  seeded using ran
1a960 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
1a970 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61  .** from the xRa
1a980 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
1a990 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
1a9a0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1a9b0 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20  ect..** ^On all 
1a9c0 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
1a9d0 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75  ations, the pseu
1a9e0 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
1a9f0 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
1aa00 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
1aa10 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
1aa20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
1aa30 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
1aa40 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69  * method..*/.voi
1aa50 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
1aa60 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
1aa70 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
1aa80 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
1aa90 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
1aaa0 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  n Callbacks.**.*
1aab0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
1aac0 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74  registers an aut
1aad0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1aae0 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
1aaf0 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
1ab00 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70  connection], sup
1ab10 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  plied in the fir
1ab20 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  st argument..** 
1ab30 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
1ab40 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1ab50 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65  ked as SQL state
1ab60 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20  ments are being 
1ab70 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b  compiled.** by [
1ab80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1ab90 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
1aba0 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ts [sqlite3_prep
1abb0 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  are_v2()],.** [s
1abc0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1abd0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1abe0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
1abf0 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a  .  ^At various.*
1ac00 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20  * points during 
1ac10 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  the compilation 
1ac20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69  process, as logi
1ac30 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74  c is being creat
1ac40 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d  ed.** to perform
1ac50 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73   various actions
1ac60 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  , the authorizer
1ac70 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1ac80 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69  oked to.** see i
1ac90 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20  f those actions 
1aca0 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54  are allowed.  ^T
1acb0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1acc0 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a  llback should.**
1acd0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1ace0 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65  OK] to allow the
1acf0 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45   action, [SQLITE
1ad00 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61  _IGNORE] to disa
1ad10 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63  llow the.** spec
1ad20 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20  ific action but 
1ad30 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74  allow the SQL st
1ad40 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69  atement to conti
1ad50 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  nue to be.** com
1ad60 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54  piled, or [SQLIT
1ad70 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65  E_DENY] to cause
1ad80 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20   the entire SQL 
1ad90 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a  statement to be.
1ada0 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68  ** rejected with
1adb0 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20   an error.  ^If 
1adc0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1add0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
1ade0 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ** any value oth
1adf0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1ae00 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45  IGNORE], [SQLITE
1ae10 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  _OK], or [SQLITE
1ae20 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74  _DENY].** then t
1ae30 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
1ae40 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
1ae50 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
1ae60 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74  t triggered.** t
1ae70 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  he authorizer wi
1ae80 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
1ae90 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
1aea0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61  *.** When the ca
1aeb0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1aec0 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74  SQLITE_OK], that
1aed0 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61   means the opera
1aee0 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65  tion.** requeste
1aef0 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20  d is ok.  ^When 
1af00 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1af10 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  urns [SQLITE_DEN
1af20 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  Y], the.** [sqli
1af30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1af40 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
1af50 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
1af60 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f  red the.** autho
1af70 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
1af80 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
1af90 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67  ssage explaining
1afa0 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20   that.** access 
1afb0 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a  is denied. .**.*
1afc0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
1afd0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1afe0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1aff0 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
1b000 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
1b010 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
1b020 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1b030 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
1b040 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
1b050 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
1b060 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
1b070 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f  integer [SQLITE_
1b080 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f  COPY | action co
1b090 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69  de] that specifi
1b0a0 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63  es.** the partic
1b0b0 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62  ular action to b
1b0c0 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54  e authorized. ^T
1b0d0 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68  he third through
1b0e0 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
1b0f0 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  s.** to the call
1b100 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65  back are zero-te
1b110 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
1b120 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64   that contain ad
1b130 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61  ditional.** deta
1b140 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
1b150 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
1b160 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rized..**.** ^If
1b170 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
1b180 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44   is [SQLITE_READ
1b190 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c  ].** and the cal
1b1a0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1b1b0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
1b1c0 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  en the.** [prepa
1b1d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73  red statement] s
1b1e0 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73  tatement is cons
1b1f0 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74  tructed to subst
1b200 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20  itute.** a NULL 
1b210 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f  value in place o
1b220 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
1b230 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  mn that would ha
1b240 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20  ve.** been read 
1b250 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
1b260 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
1b270 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  .  The [SQLITE_I
1b280 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e  GNORE].** return
1b290 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1b2a0 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65  deny an untruste
1b2b0 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f  d user access to
1b2c0 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63   individual.** c
1b2d0 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c  olumns of a tabl
1b2e0 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  e..** ^If the ac
1b2f0 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
1b300 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64  LITE_DELETE] and
1b310 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1b320 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
1b330 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
1b340 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61  e [DELETE] opera
1b350 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75  tion proceeds bu
1b360 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61  t the.** [trunca
1b370 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d  te optimization]
1b380 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64   is disabled and
1b390 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65   all rows are de
1b3a0 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c  leted individual
1b3b0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74  ly..**.** An aut
1b3c0 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20  horizer is used 
1b3d0 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  when [sqlite3_pr
1b3e0 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e  epare | preparin
1b3f0 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  g].** SQL statem
1b400 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74  ents from an unt
1b410 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74  rusted source, t
1b420 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  o ensure that th
1b430 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
1b440 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74  .** do not try t
1b450 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68  o access data th
1b460 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77  ey are not allow
1b470 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68  ed to see, or th
1b480 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
1b490 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65  * try to execute
1b4a0 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65   malicious state
1b4b0 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67  ments that damag
1b4c0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  e the database. 
1b4d0 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
1b4e0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
1b4f0 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72  may allow a user
1b500 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72   to enter arbitr
1b510 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69  ary.** SQL queri
1b520 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f  es for evaluatio
1b530 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e  n by a database.
1b540 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63    But the applic
1b550 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ation does.** no
1b560 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20  t want the user 
1b570 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61  to be able to ma
1b580 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61  ke arbitrary cha
1b590 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  nges to the.** d
1b5a0 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74  atabase.  An aut
1b5b0 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68  horizer could th
1b5c0 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61  en be put in pla
1b5d0 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20  ce while the.** 
1b5e0 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c  user-entered SQL
1b5f0 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74   is being [sqlit
1b600 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
1b610 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64  pared] that.** d
1b620 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68  isallows everyth
1b630 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45  ing except [SELE
1b640 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  CT] statements..
1b650 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
1b660 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20  ns that need to 
1b670 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d  process SQL from
1b680 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
1b690 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f  es.** might also
1b6a0 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69   consider loweri
1b6b0 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69  ng resource limi
1b6c0 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ts using [sqlite
1b6d0 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e  3_limit()].** an
1b6e0 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62  d limiting datab
1b6f0 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74  ase size using t
1b700 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  he [max_page_cou
1b710 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20  nt] [PRAGMA].** 
1b720 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75  in addition to u
1b730 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a  sing an authoriz
1b740 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79  er..**.** ^(Only
1b750 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
1b760 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
1b770 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
1b780 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1b790 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
1b7a0 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
1b7b0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1b7c0 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
1b7d0 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
1b7e0 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65  )^  ^Disable the
1b7f0 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69   authorizer by i
1b800 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c  nstalling a NULL
1b810 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68   callback..** Th
1b820 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  e authorizer is 
1b830 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
1b840 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ult..**.** The a
1b850 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1b860 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
1b870 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
1b880 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
1b890 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b8a0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
1b8b0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1b8c0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74  callback..** Not
1b8d0 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
1b8e0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
1b8f0 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
1b900 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
1b910 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
1b920 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
1b930 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
1b940 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
1b950 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
1b960 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  * ^When [sqlite3
1b970 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
1b980 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72  s used to prepar
1b990 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  e a statement, t
1b9a0 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  he.** statement 
1b9b0 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70  might be re-prep
1b9c0 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c  ared during [sql
1b9d0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65  ite3_step()] due
1b9e0 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61   to a .** schema
1b9f0 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c   change.  Hence,
1ba00 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1ba10 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74   should ensure t
1ba20 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  hat the.** corre
1ba30 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ct authorizer ca
1ba40 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69  llback remains i
1ba50 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74  n place during t
1ba60 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
1ba70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65  ()]..**.** ^Note
1ba80 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
1ba90 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1baa0 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
1bab0 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ring.** [sqlite3
1bac0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
1bad0 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
1bae0 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
1baf0 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
1bb00 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
1bb10 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
1bb20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
1bb30 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74   unless.** as st
1bb40 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76  ated in the prev
1bb50 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20  ious paragraph, 
1bb60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
1bb70 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65  nvokes.** sqlite
1bb80 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74  3_prepare_v2() t
1bb90 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74  o reprepare a st
1bba0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20  atement after a 
1bbb0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a  schema change..*
1bbc0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65  /.int sqlite3_se
1bbd0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20  t_authorizer(.  
1bbe0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20  sqlite3*,.  int 
1bbf0 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69  (*xAuth)(void*,i
1bc00 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  nt,const char*,c
1bc10 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1bc20 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
1bc30 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73  r*),.  void *pUs
1bc40 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  erData.);../*.**
1bc50 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
1bc60 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64  rizer Return Cod
1bc70 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
1bc80 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1bc90 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
1bca0 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
1bcb0 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74  ion] must.** ret
1bcc0 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49  urn either [SQLI
1bcd0 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66  TE_OK] or one of
1bce0 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74   these two const
1bcf0 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  ants in order.**
1bd00 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74   to signal SQLit
1bd10 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  e whether or not
1bd20 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70   the action is p
1bd30 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74  ermitted.  See t
1bd40 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
1bd50 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
1bd60 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d  authorizer docum
1bd70 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64  entation] for ad
1bd80 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
1bd90 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e  rmation..**.** N
1bda0 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f  ote that SQLITE_
1bdb0 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75  IGNORE is also u
1bdc0 73 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45  sed as a [SQLITE
1bdd0 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75  _ROLLBACK | retu
1bde0 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d  rn code].** from
1bdf0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74   the [sqlite3_vt
1be00 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
1be10 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
1be20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1be30 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
1be40 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
1be50 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
1be60 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
1be70 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
1be80 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
1be90 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
1bea0 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
1beb0 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
1bec0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
1bed0 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
1bee0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
1bef0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1bf00 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
1bf10 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
1bf20 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
1bf30 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
1bf40 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
1bf50 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
1bf60 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
1bf70 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
1bf80 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
1bf90 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
1bfa0 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
1bfb0 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
1bfc0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
1bfd0 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
1bfe0 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
1bff0 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
1c000 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
1c010 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
1c020 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
1c030 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
1c040 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
1c050 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
1c060 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
1c070 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
1c080 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
1c090 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
1c0a0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
1c0b0 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
1c0c0 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
1c0d0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
1c0e0 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
1c0f0 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
1c100 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
1c110 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
1c120 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
1c130 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
1c140 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
1c150 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1c160 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1c170 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
1c180 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
1c190 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
1c1a0 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
1c1b0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
1c1c0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1c1d0 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
1c1e0 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
1c1f0 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
1c200 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
1c210 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
1c220 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
1c230 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
1c240 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
1c250 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
1c260 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
1c270 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
1c280 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c290 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c2a0 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
1c2b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
1c2c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
1c2d0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1c2e0 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
1c2f0 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
1c300 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1c310 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1c320 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1c330 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
1c340 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1c350 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1c360 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1c370 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1c380 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
1c390 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1c3a0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1c3b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1c3c0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1c3d0 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
1c3e0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1c3f0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1c400 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1c410 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1c420 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
1c430 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1c440 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1c450 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1c460 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1c470 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
1c480 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1c490 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1c4a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1c4b0 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
1c4c0 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
1c4d0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1c4e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1c4f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c500 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
1c510 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
1c520 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1c530 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1c540 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c550 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
1c560 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
1c570 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1c580 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1c590 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c5a0 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
1c5b0 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
1c5c0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1c5d0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1c5e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c5f0 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
1c600 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
1c610 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1c620 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1c630 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1c640 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
1c650 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
1c660 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1c670 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1c680 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1c690 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
1c6a0 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
1c6b0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1c6c0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1c6d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1c6e0 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
1c6f0 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
1c700 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1c710 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1c720 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1c730 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
1c740 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
1c750 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1c760 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1c770 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1c780 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
1c790 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
1c7a0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1c7b0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1c7c0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
1c7d0 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
1c7e0 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
1c7f0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1c800 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1c810 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
1c820 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
1c830 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1c840 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1c850 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1c860 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
1c870 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
1c880 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
1c890 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
1c8a0 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
1c8b0 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
1c8c0 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
1c8d0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1c8e0 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
1c8f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1c900 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
1c910 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
1c920 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
1c930 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1c940 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1c950 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
1c960 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
1c970 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
1c980 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1c990 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1c9a0 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
1c9b0 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
1c9c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1c9d0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
1c9e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c9f0 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
1ca00 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
1ca10 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
1ca20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1ca30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ca40 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
1ca50 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
1ca60 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
1ca70 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1ca80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ca90 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
1caa0 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
1cab0 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
1cac0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1cad0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1cae0 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
1caf0 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
1cb00 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
1cb10 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1cb20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1cb30 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
1cb40 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
1cb50 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1cb60 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1cb70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1cb80 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
1cb90 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
1cba0 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
1cbb0 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
1cbc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1cbd0 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
1cbe0 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
1cbf0 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
1cc00 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1cc10 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
1cc20 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
1cc30 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
1cc40 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
1cc50 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
1cc60 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
1cc70 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
1cc80 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
1cc90 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
1cca0 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
1ccb0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
1ccc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1ccd0 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
1cce0 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   used */../*.** 
1ccf0 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e  CAPI3REF: Tracin
1cd00 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20  g And Profiling 
1cd10 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1cd20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1cd30 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
1cd40 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
1cd50 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a  can be used for.
1cd60 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70  ** tracing and p
1cd70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65  rofiling the exe
1cd80 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74  cution of SQL st
1cd90 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
1cda0 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
1cdb0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
1cdc0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61  d by sqlite3_tra
1cdd0 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ce() is invoked 
1cde0 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69  at.** various ti
1cdf0 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20  mes when an SQL 
1ce00 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69  statement is bei
1ce10 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74  ng run by [sqlit
1ce20 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e  e3_step()]..** ^
1ce30 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
1ce40 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e() callback is 
1ce50 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55  invoked with a U
1ce60 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
1ce70 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61  f the.** SQL sta
1ce80 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74  tement text as t
1ce90 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
1cea0 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
1ceb0 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69  ing..** ^(Additi
1cec0 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61  onal sqlite3_tra
1ced0 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d  ce() callbacks m
1cee0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73  ight occur.** as
1cef0 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20   each triggered 
1cf00 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
1cf10 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
1cf20 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
1cf30 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
1cf40 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
1cf50 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
1cf60 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e  s the trigger.)^
1cf70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
1cf80 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
1cf90 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
1cfa0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
1cfb0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
1cfc0 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
1cfd0 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68  t finishes.  ^Th
1cfe0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
1cff0 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
1d000 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
1d010 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
1d020 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
1d030 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
1d040 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
1d050 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
1d060 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70   to run.  ^The p
1d070 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a  rofile callback.
1d080 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e  ** time is in un
1d090 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  its of nanosecon
1d0a0 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  ds, however the 
1d0b0 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
1d0c0 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c  tation.** is onl
1d0d0 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c  y capable of mil
1d0e0 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74  lisecond resolut
1d0f0 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c  ion so the six l
1d100 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  east significant
1d110 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68  .** digits in th
1d120 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69  e time are meani
1d130 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20  ngless.  Future 
1d140 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1d150 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76  te.** might prov
1d160 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f  ide greater reso
1d170 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72  lution on the pr
1d180 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  ofiler callback.
1d190 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
1d1a0 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74  _profile() funct
1d1b0 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ion is considere
1d1c0 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  d experimental a
1d1d0 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74  nd is.** subject
1d1e0 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75   to change in fu
1d1f0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
1d200 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64   SQLite..*/.void
1d210 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
1d220 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
1d230 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
1d240 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
1d250 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  *);.SQLITE_EXPER
1d260 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71  IMENTAL void *sq
1d270 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
1d280 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
1d290 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
1d2a0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
1d2b0 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
1d2c0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1d2d0 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
1d2e0 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a  gress Callbacks.
1d2f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1d300 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1d310 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74  ler(D,N,X,P) int
1d320 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
1d330 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  e callback.** fu
1d340 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69  nction X to be i
1d350 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
1d360 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
1d370 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
1d380 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
1d390 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
1d3a0 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tep()] and [sqli
1d3b0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
1d3c0 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65   for.** database
1d3d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
1d3e0 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
1d3f0 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
1d400 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
1d410 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
1d420 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
1d430 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ry..**.** ^The p
1d440 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61  arameter P is pa
1d450 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
1d460 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
1d470 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61  er to the .** ca
1d480 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1d490 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  X.  ^The paramet
1d4a0 65 72 20 4e 20 69 73 20 74 68 65 20 6e 75 6d 62  er N is the numb
1d4b0 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75  er of .** [virtu
1d4c0 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72  al machine instr
1d4d0 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72  uctions] that ar
1d4e0 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77  e evaluated betw
1d4f0 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a  een successive.*
1d500 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
1d510 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e   the callback X.
1d520 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73  .**.** ^Only a s
1d530 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68  ingle progress h
1d540 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65  andler may be de
1d550 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d  fined at one tim
1d560 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61  e per.** [databa
1d570 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20  se connection]; 
1d580 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72  setting a new pr
1d590 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
1d5a0 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c  ancels the.** ol
1d5b0 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67  d one.  ^Setting
1d5c0 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20   parameter X to 
1d5d0 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68  NULL disables th
1d5e0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1d5f0 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67  er..** ^The prog
1d600 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20  ress handler is 
1d610 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79  also disabled by
1d620 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20   setting N to a 
1d630 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68  value less.** th
1d640 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  an 1..**.** ^If 
1d650 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
1d660 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
1d670 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
1d680 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
1d690 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
1d6a0 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
1d6b0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
1d6c0 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
1d6d0 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
1d6e0 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
1d6f0 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
1d700 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
1d710 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
1d720 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
1d730 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
1d740 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1d750 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1d760 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73  oked the progres
1d770 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f  s handler..** No
1d780 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
1d790 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
1d7a0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
1d7b0 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
1d7c0 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
1d7d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
1d7e0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
1d7f0 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
1d800 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
1d810 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
1d820 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
1d830 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20  (sqlite3*, int, 
1d840 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
1d850 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1d860 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20  PI3REF: Opening 
1d870 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43  A New Database C
1d880 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onnection.**.** 
1d890 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1d8a0 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
1d8b0 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20  atabase file as 
1d8c0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
1d8d0 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72   .** filename ar
1d8e0 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
1d8f0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
1d900 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
1d910 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
1d920 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1d930 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1d940 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
1d950 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1d960 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
1d970 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1d980 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
1d990 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
1d9a0 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
1d9b0 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
1d9c0 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
1d9d0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
1d9e0 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
1d9f0 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
1da00 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
1da10 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
1da20 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1da30 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
1da40 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
1da50 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
1da60 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
1da70 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
1da80 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
1da90 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
1daa0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1dab0 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
1dac0 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
1dad0 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
1dae0 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
1daf0 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
1db00 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
1db10 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
1db20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
1db30 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
1db40 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1db50 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
1db60 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
1db70 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
1db80 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
1db90 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
1dba0 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
1dbb0 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
1dbc0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
1dbd0 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
1dbe0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
1dbf0 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
1dc00 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  the database wil
1dc10 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a  l be UTF-8 if.**
1dc20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1dc30 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
1dc40 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  v2() is called a
1dc50 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20  nd.** UTF-16 in 
1dc60 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
1dc70 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33  order if sqlite3
1dc80 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65  _open16() is use
1dc90 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  d..**.** Whether
1dca0 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
1dcb0 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
1dcc0 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
1dcd0 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74  rces.** associat
1dce0 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
1dcf0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1dd00 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
1dd10 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a  be released by.*
1dd20 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  * passing it to 
1dd30 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
1dd40 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
1dd50 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
1dd60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1dd70 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74  e3_open_v2() int
1dd80 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b  erface works lik
1dd90 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
1dda0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
1ddb0 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61  it accepts two a
1ddc0 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65  dditional parame
1ddd0 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f  ters for additio
1dde0 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f  nal control.** o
1ddf0 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61  ver the new data
1de00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
1de10 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61    ^(The flags pa
1de20 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71  rameter to.** sq
1de30 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1de40 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a  can take one of.
1de50 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
1de60 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f   three values, o
1de70 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
1de80 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
1de90 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1dea0 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
1deb0 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20  PEN_FULLMUTEX], 
1dec0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
1ded0 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53  REDCACHE],.** [S
1dee0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
1def0 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72  TECACHE], and/or
1df00 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
1df10 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a  I] flags:)^.**.*
1df20 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e  * <dl>.** ^(<dt>
1df30 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1df40 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  DONLY]</dt>.** <
1df50 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1df60 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61  is opened in rea
1df70 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66  d-only mode.  If
1df80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
1df90 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64  es not.** alread
1dfa0 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
1dfb0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
1dfc0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1dfd0 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
1dfe0 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a  EADWRITE]</dt>.*
1dff0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
1e000 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
1e010 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
1e020 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
1e030 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20  , or reading.** 
1e040 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65  only if the file
1e050 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
1e060 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61  ted by the opera
1e070 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e  ting system.  In
1e080 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20   either.** case 
1e090 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73  the database mus
1e0a0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  t already exist,
1e0b0 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   otherwise an er
1e0c0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
1e0d0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1e0e0 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
1e0f0 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
1e100 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1e110 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
1e120 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1e130 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
1e140 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61  g and writing, a
1e150 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66  nd is created if
1e160 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
1e170 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
1e180 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
1e190 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
1e1a0 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
1e1b0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
1e1c0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
1e1d0 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  ().</dd>)^.** </
1e1e0 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  dl>.**.** If the
1e1f0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
1e200 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1e210 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  2() is not one o
1e220 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
1e230 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
1e240 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  e optionally com
1e250 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72  bined with other
1e260 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1e270 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49  _READONLY | SQLI
1e280 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a  TE_OPEN_* bits].
1e290 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
1e2a0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
1e2b0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
1e2c0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
1e2d0 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
1e2e0 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  et, then the dat
1e2f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e300 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65  .** opens in the
1e310 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   multi-thread [t
1e320 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
1e330 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69  s long as the si
1e340 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d  ngle-thread.** m
1e350 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ode has not been
1e360 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
1e370 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
1e380 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  me.  ^If the.** 
1e390 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
1e3a0 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  LMUTEX] flag is 
1e3b0 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74  set then the dat
1e3c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e3d0 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65   opens.** in the
1e3e0 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
1e3f0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c  eading mode] unl
1e400 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  ess single-threa
1e410 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75  d was.** previou
1e420 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20  sly selected at 
1e430 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
1e440 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e  start-time..** ^
1e450 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
1e460 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c  _SHAREDCACHE] fl
1e470 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
1e480 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1e490 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69  n to be.** eligi
1e4a0 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72  ble to use [shar
1e4b0 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20  ed cache mode], 
1e4c0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
1e4d0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
1e4e0 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
1e4f0 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73  enabled using [s
1e500 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
1e510 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20  ared_cache()].  
1e520 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ^The.** [SQLITE_
1e530 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
1e540 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
1e550 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1e560 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a  ection to not.**
1e570 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20   participate in 
1e580 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
1e590 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69  de] even if it i
1e5a0 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
1e5b0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
1e5c0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1e5d0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
1e5e0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
1e5f0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
1e600 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
1e610 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
1e620 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
1e630 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
1e640 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
1e650 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
1e660 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72  e.  ^If the four
1e670 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
1e680 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
1e690 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
1e6a0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
1e6b0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
1e6c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
1e6d0 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d  ilename is ":mem
1e6e0 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72  ory:", then a pr
1e6f0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
1e700 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
1e710 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65  ase.** is create
1e720 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  d for the connec
1e730 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d  tion.  ^This in-
1e740 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20  memory database 
1e750 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e  will vanish when
1e760 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1e770 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
1e780 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76  losed.  Future v
1e790 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1e7a0 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20  e might.** make 
1e7b0 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61  use of additiona
1e7c0 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61  l special filena
1e7d0 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77  mes that begin w
1e7e0 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72  ith the ":" char
1e7f0 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20  acter..** It is 
1e800 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
1e810 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
1e820 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c   filename actual
1e830 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69  ly does begin wi
1e840 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72  th.** a ":" char
1e850 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64  acter you should
1e860 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65   prefix the file
1e870 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68  name with a path
1e880 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20  name such as.** 
1e890 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d  "./" to avoid am
1e8a0 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  biguity..**.** ^
1e8b0 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
1e8c0 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  is an empty stri
1e8d0 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  ng, then a priva
1e8e0 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a  te, temporary.**
1e8f0 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73   on-disk databas
1e900 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65  e will be create
1e910 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74  d.  ^This privat
1e920 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
1e930 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  be.** automatica
1e940 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73  lly deleted as s
1e950 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62  oon as the datab
1e960 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
1e970 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
1e980 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  [[URI filenames 
1e990 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  in sqlite3_open(
1e9a0 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65  )]] <h3>URI File
1e9b0 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  names</h3>.**.**
1e9c0 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61   ^If [URI filena
1e9d0 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69  me] interpretati
1e9e0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61  on is enabled, a
1e9f0 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  nd the filename 
1ea00 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69  argument.** begi
1ea10 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c  ns with "file:",
1ea20 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61   then the filena
1ea30 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  me is interprete
1ea40 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49  d as a URI. ^URI
1ea50 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  .** filename int
1ea60 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
1ea70 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53  nabled if the [S
1ea80 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
1ea90 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69  flag is.** set i
1eaa0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
1eab0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
1eac0 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69  _open_v2(), or i
1ead0 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e  f it has.** been
1eae0 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c   enabled globall
1eaf0 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  y using the [SQL
1eb00 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20  ITE_CONFIG_URI] 
1eb10 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a  option with the.
1eb20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
1eb30 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20  ig()] method or 
1eb40 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  by the [SQLITE_U
1eb50 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d  SE_URI] compile-
1eb60 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
1eb70 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  As of SQLite ver
1eb80 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20  sion 3.7.7, URI 
1eb90 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
1eba0 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65  etation is turne
1ebb0 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61  d off.** by defa
1ebc0 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20  ult, but future 
1ebd0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
1ebe0 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20  te might enable 
1ebf0 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  URI filename.** 
1ec00 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62  interpretation b
1ec10 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20  y default.  See 
1ec20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d  "[URI filenames]
1ec30 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  " for additional
1ec40 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
1ec50 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  .**.** URI filen
1ec60 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20  ames are parsed 
1ec70 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43  according to RFC
1ec80 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55   3986. ^If the U
1ec90 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a  RI contains an.*
1eca0 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65  * authority, the
1ecb0 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74  n it must be eit
1ecc0 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72  her an empty str
1ecd0 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e  ing or the strin
1ece0 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74  g .** "localhost
1ecf0 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  ". ^If the autho
1ed00 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65  rity is not an e
1ed10 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22  mpty string or "
1ed20 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a  localhost", an .
1ed30 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  ** error is retu
1ed40 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c  rned to the call
1ed50 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e  er. ^The fragmen
1ed60 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
1ed70 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65   URI, if .** pre
1ed80 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64  sent, is ignored
1ed90 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
1eda0 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f  uses the path co
1edb0 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55  mponent of the U
1edc0 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f  RI as the name o
1edd0 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a  f the disk file.
1ede0 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e  ** which contain
1edf0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  s the database. 
1ee00 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67  ^If the path beg
1ee10 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63  ins with a '/' c
1ee20 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68  haracter, .** th
1ee30 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72  en it is interpr
1ee40 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c  eted as an absol
1ee50 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68  ute path. ^If th
1ee60 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20  e path does not 
1ee70 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61  begin .** with a
1ee80 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68   '/' (meaning th
1ee90 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  at the authority
1eea0 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74   section is omit
1eeb0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49  ted from the URI
1eec0 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61  ).** then the pa
1eed0 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  th is interprete
1eee0 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20  d as a relative 
1eef0 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69  path. .** ^On wi
1ef00 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74  ndows, the first
1ef10 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e   component of an
1ef20 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a   absolute path .
1ef30 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70  ** is a drive sp
1ef40 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67  ecification (e.g
1ef50 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b  . "C:")..**.** [
1ef60 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20  [core URI query 
1ef70 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20  parameters]].** 
1ef80 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  The query compon
1ef90 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79  ent of a URI may
1efa0 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74   contain paramet
1efb0 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74  ers that are int
1efc0 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68  erpreted.** eith
1efd0 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73  er by SQLite its
1efe0 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46  elf, or by a [VF
1eff0 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69  S | custom VFS i
1f000 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a  mplementation]..
1f010 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70  ** SQLite interp
1f020 72 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69  rets the followi
1f030 6e 67 20 74 68 72 65 65 20 71 75 65 72 79 20 70  ng three query p
1f040 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a  arameters:.**.**
1f050 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
1f060 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65  <b>vfs</b>: ^The
1f070 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72   "vfs" parameter
1f080 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20   may be used to 
1f090 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65  specify the name
1f0a0 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53   of.**     a VFS
1f0b0 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f   object that pro
1f0c0 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74  vides the operat
1f0d0 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
1f0e0 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64  face that should
1f0f0 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20  .**     be used 
1f100 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
1f110 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64  tabase file on d
1f120 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70  isk. ^If this op
1f130 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a  tion is set to.*
1f140 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73  *     an empty s
1f150 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c  tring the defaul
1f160 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20  t VFS object is 
1f170 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e  used. ^Specifyin
1f180 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20  g an unknown.** 
1f190 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72      VFS is an er
1f1a0 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  ror. ^If sqlite3
1f1b0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
1f1c0 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f  ed and the vfs o
1f1d0 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
1f1e0 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68  present, then th
1f1f0 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20  e VFS specified 
1f200 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61  by the option ta
1f210 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f  kes precedence o
1f220 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76  ver.**     the v
1f230 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
1f240 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1f250 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
1f260 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
1f270 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f    <li> <b>mode</
1f280 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70  b>: ^(The mode p
1f290 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
1f2a0 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72  set to either "r
1f2b0 6f 22 2c 20 22 72 77 22 20 6f 72 0a 2a 2a 20 20  o", "rw" or.**  
1f2c0 20 20 20 22 72 77 63 22 2e 20 41 74 74 65 6d 70     "rwc". Attemp
1f2d0 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74  ting to set it t
1f2e0 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75  o any other valu
1f2f0 65 20 69 73 20 61 6e 20 65 72 72 6f 72 29 5e 2e  e is an error)^.
1f300 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f   .**     ^If "ro
1f310 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20  " is specified, 
1f320 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
1f330 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
1f340 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20  read-only .**   
1f350 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61    access, just a
1f360 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  s if the [SQLITE
1f370 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20  _OPEN_READONLY] 
1f380 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65  flag had been se
1f390 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20  t in the .**    
1f3a0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
1f3b0 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  to sqlite3_prepa
1f3c0 72 65 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65  re_v2(). ^If the
1f3d0 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20   mode option is 
1f3e0 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22  set to .**     "
1f3f0 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61  rw", then the da
1f400 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1f410 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20   for read-write 
1f420 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29  (but not create)
1f430 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
1f440 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50   as if SQLITE_OP
1f450 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75  EN_READWRITE (bu
1f460 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45  t not SQLITE_OPE
1f470 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a  N_CREATE) had .*
1f480 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20  *     been set. 
1f490 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20  ^Value "rwc" is 
1f4a0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
1f4b0 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20  tting both .**  
1f4c0 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52     SQLITE_OPEN_R
1f4d0 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c  EADWRITE and SQL
1f4e0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e  ITE_OPEN_CREATE.
1f4f0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
1f500 6e 5f 76 32 28 29 20 69 73 20 0a 2a 2a 20 20 20  n_v2() is .**   
1f510 20 20 75 73 65 64 2c 20 69 74 20 69 73 20 61 6e    used, it is an
1f520 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66   error to specif
1f530 79 20 61 20 76 61 6c 75 65 20 66 6f 72 20 74 68  y a value for th
1f540 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
1f550 20 74 68 61 74 20 69 73 20 0a 2a 2a 20 20 20 20   that is .**    
1f560 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76   less restrictiv
1f570 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63  e than that spec
1f580 69 66 69 65 64 20 62 79 20 74 68 65 20 66 6c 61  ified by the fla
1f590 67 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65  gs passed as the
1f5a0 20 74 68 69 72 64 20 0a 2a 2a 20 20 20 20 20 70   third .**     p
1f5b0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1f5c0 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c    <li> <b>cache<
1f5d0 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20  /b>: ^The cache 
1f5e0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
1f5f0 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
1f600 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20  shared" or.**   
1f610 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65    "private". ^Se
1f620 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61  tting it to "sha
1f630 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65  red" is equivale
1f640 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
1f650 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  e.**     SQLITE_
1f660 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
1f670 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67   bit in the flag
1f680 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  s argument passe
1f690 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69  d to.**     sqli
1f6a0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
1f6b0 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68  Setting the cach
1f6c0 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22  e parameter to "
1f6d0 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20  private" is .** 
1f6e0 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74      equivalent t
1f6f0 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51  o setting the SQ
1f700 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
1f710 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20  ECACHE bit..**  
1f720 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f     ^If sqlite3_o
1f730 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
1f740 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22   and the "cache"
1f750 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
1f760 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20  esent in.**     
1f770 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20  a URI filename, 
1f780 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69  its value overri
1f790 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 75  des any behaviou
1f7a0 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73  r requested by s
1f7b0 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51  etting.**     SQ
1f7c0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
1f7d0 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45  ECACHE or SQLITE
1f7e0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
1f7f0 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  E flag..** </ul>
1f800 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69  .**.** ^Specifyi
1f810 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61  ng an unknown pa
1f820 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71  rameter in the q
1f830 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
1f840 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61  f a URI is not a
1f850 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74  n.** error.  Fut
1f860 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1f870 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64  SQLite might und
1f880 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e  erstand addition
1f890 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61  al query.** para
1f8a0 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71  meters.  See "[q
1f8b0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20  uery parameters 
1f8c0 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61  with special mea
1f8d0 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22  ning to SQLite]"
1f8e0 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
1f8f0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
1f900 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
1f910 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20  name examples]] 
1f920 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65  <h3>URI filename
1f930 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a   examples</h3>.*
1f940 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  *.** <table bord
1f950 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e  er="1" align=cen
1f960 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  ter cellpadding=
1f970 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55  5>.** <tr><th> U
1f980 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68  RI filenames <th
1f990 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72  > Results.** <tr
1f9a0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
1f9b0 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
1f9c0 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69       Open the fi
1f9d0 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
1f9e0 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
1f9f0 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ctory..** <tr><t
1fa00 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
1fa10 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a  ed/data.db<br>.*
1fa20 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
1fa30 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ///home/fred/dat
1fa40 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20  a.db <br> .**   
1fa50 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f         file://lo
1fa60 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65  calhost/home/fre
1fa70 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c  d/data.db <br> <
1fa80 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
1fa90 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   Open the databa
1faa0 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  se file "/home/f
1fab0 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a  red/data.db"..**
1fac0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
1fad0 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66  /darkstar/home/f
1fae0 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e  red/data.db <td>
1faf0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
1fb00 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61   error. "darksta
1fb10 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f  r" is not a reco
1fb20 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79  gnized authority
1fb30 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79  ..** <tr><td sty
1fb40 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a  le="white-space:
1fb50 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20  nowrap"> .**    
1fb60 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a        file:///C:
1fb70 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64  /Documents%20and
1fb80 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64  %20Settings/fred
1fb90 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62  /Desktop/data.db
1fba0 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e  .**     <td> Win
1fbb0 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20  dows only: Open 
1fbc0 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
1fbd0 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73  b" on fred's des
1fbe0 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a  ktop on drive.**
1fbf0 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f            C:. No
1fc00 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20  te that the %20 
1fc10 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73  escaping in this
1fc20 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20   example is not 
1fc30 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20  strictly .**    
1fc40 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20        necessary 
1fc50 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65  - space characte
1fc60 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c  rs can be used l
1fc70 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20  iterally.**     
1fc80 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65       in URI file
1fc90 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  names..** <tr><t
1fca0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
1fcb0 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72  mode=ro&cache=pr
1fcc0 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20  ivate <td> .**  
1fcd0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
1fce0 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
1fcf0 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
1fd00 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e  tory for read-on
1fd10 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20  ly access..**   
1fd20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73         Regardles
1fd30 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
1fd40 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65  not shared-cache
1fd50 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
1fd60 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   by.**          
1fd70 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70  default, use a p
1fd80 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a  rivate cache..**
1fd90 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
1fda0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
1fdb0 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63  b?vfs=unix-noloc
1fdc0 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20  k <td>.**       
1fdd0 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68     Open file "/h
1fde0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
1fdf0 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69  ". Use the speci
1fe00 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c  al VFS "unix-nol
1fe10 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ock"..** <tr><td
1fe20 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
1fe30 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64  ode=readonly <td
1fe40 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
1fe50 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e  n error. "readon
1fe60 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c  ly" is not a val
1fe70 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68  id option for th
1fe80 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74  e "mode" paramet
1fe90 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  er..** </table>.
1fea0 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64  **.** ^URI hexad
1feb0 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
1fec0 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72  quences (%HH) ar
1fed0 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68  e supported with
1fee0 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a  in the path and.
1fef0 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  ** query compone
1ff00 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20  nts of a URI. A 
1ff10 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
1ff20 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73  pe sequence cons
1ff30 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72  ists of a.** per
1ff40 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20  cent sign - "%" 
1ff50 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78  - followed by ex
1ff60 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65  actly two hexade
1ff70 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a  cimal digits .**
1ff80 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f   specifying an o
1ff90 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66  ctet value. ^Bef
1ffa0 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20  ore the path or 
1ffb0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
1ffc0 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c   of a.** URI fil
1ffd0 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70  ename are interp
1ffe0 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20  reted, they are 
1fff0 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
20000 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20  F-8 and all .** 
20010 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
20020 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70  pe sequences rep
20030 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c  laced by a singl
20040 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e  e byte containin
20050 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70  g the.** corresp
20060 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66  onding octet. If
20070 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65   this process ge
20080 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c  nerates an inval
20090 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  id UTF-8 encodin
200a0 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  g,.** the result
200b0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
200c0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
200d0 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
200e0 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
200f0 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
20100 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
20110 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
20120 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
20130 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
20140 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
20150 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
20160 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
20170 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
20180 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
20190 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
201a0 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
201b0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
201c0 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
201d0 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
201e0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
201f0 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
20200 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 69 6e  open_v2()..*/.in
20210 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
20220 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
20230 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
20240 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
20250 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
20260 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
20270 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
20280 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
20290 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
202a0 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
202b0 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
202c0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
202d0 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
202e0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
202f0 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
20300 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
20310 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
20320 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
20330 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
20340 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
20350 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
20360 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
20370 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
20380 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
20390 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
203a0 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
203b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
203c0 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
203d0 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
203e0 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
203f0 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
20400 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20410 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65  EF: Obtain Value
20420 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65  s For URI Parame
20430 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ters.**.** These
20440 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75   are utility rou
20450 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f  tines, useful to
20460 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
20470 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b  ions, that check
20480 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20  .** to see if a 
20490 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
204a0 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e  s a URI that con
204b0 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69  tained a specifi
204c0 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61  c query .** para
204d0 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f  meter, and if so
204e0 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c   obtains the val
204f0 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79  ue of that query
20500 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
20510 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61  * If F is the da
20520 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
20530 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69  pointer passed i
20540 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20  nto the xOpen() 
20550 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20  method of .** a 
20560 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
20570 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67  on when the flag
20580 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  s parameter to x
20590 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f  Open() has one o
205a0 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68  r .** more of th
205b0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
205c0 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  RI] or [SQLITE_O
205d0 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74  PEN_MAIN_DB] bit
205e0 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69  s set and.** P i
205f0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
20600 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
20610 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  r, then.** sqlit
20620 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
20630 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68  (F,P) returns th
20640 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50  e value of the P
20650 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66  .** parameter if
20660 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20   it exists or a 
20670 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
20680 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61  P does not appea
20690 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79  r as a .** query
206a0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e   parameter on F.
206b0 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72    If P is a quer
206c0 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46  y parameter of F
206d0 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69  .** has no expli
206e0 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  cit value, then 
206f0 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
20700 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
20710 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ns.** a pointer 
20720 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
20730 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ng..**.** The sq
20740 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
20750 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
20760 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20   assumes that P 
20770 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20  is a boolean.** 
20780 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
20790 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f  turns true (1) o
207a0 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f  r false (0) acco
207b0 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c  rding to the val
207c0 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65  ue.** of P.  The
207d0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
207e0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
207f0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ine returns true
20800 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76   (1) if the.** v
20810 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61  alue of query pa
20820 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
20830 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65   of "yes", "true
20840 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e  ", or "on" in an
20850 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20  y.** case or if 
20860 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
20870 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f   with a non-zero
20880 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a   number.  The .*
20890 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
208a0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
208b0 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61  tines returns fa
208c0 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76  lse (0) if the v
208d0 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79  alue of.** query
208e0 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
208f0 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61  one of "no", "fa
20900 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69  lse", or "off" i
20910 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a  n any case or.**
20920 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
20930 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65  gins with a nume
20940 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20  ric zero.  If P 
20950 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a  is not a query.*
20960 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  * parameter on F
20970 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
20980 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f   of P is does no
20990 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74  t match any of t
209a0 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65  he.** above, the
209b0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  n sqlite3_uri_bo
209c0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
209d0 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a  urns (B!=0)..**.
209e0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
209f0 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20  ri_int64(F,P,D) 
20a00 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73  routine converts
20a10 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
20a20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74  into a.** 64-bit
20a30 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
20a40 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74  and returns that
20a50 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69   integer, or D i
20a60 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  f P does not.** 
20a70 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76  exist.  If the v
20a80 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d  alue of P is som
20a90 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
20aa0 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  n an integer, th
20ab0 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65  en.** zero is re
20ac0 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49  turned..** .** I
20ad0 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f F is a NULL po
20ae0 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69  inter, then sqli
20af0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
20b00 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e  r(F,P) returns N
20b10 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  ULL and.** sqlit
20b20 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
20b30 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e  ,P,B) returns B.
20b40 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20    If F is not a 
20b50 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
20b60 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74  .** is not a dat
20b70 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e  abase file pathn
20b80 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ame pointer that
20b90 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69   SQLite passed i
20ba0 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a  nto the xOpen.**
20bb0 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65   VFS method, the
20bc0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
20bd0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  f this routine i
20be0 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
20bf0 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65  probably.** unde
20c00 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73  sirable..*/.cons
20c10 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
20c20 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f  uri_parameter(co
20c30 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
20c40 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ame, const char 
20c50 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71  *zParam);.int sq
20c60 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
20c70 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  n(const char *zF
20c80 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ile, const char 
20c90 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65  *zParam, int bDe
20ca0 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f  fault);.sqlite3_
20cb0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72  int64 sqlite3_ur
20cc0 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68  i_int64(const ch
20cd0 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  ar*, const char*
20ce0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
20cf0 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
20d00 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
20d10 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a  And Messages.**.
20d20 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
20d30 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66  errcode() interf
20d40 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
20d50 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
20d60 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
20d70 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
20d80 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20  e] for the most 
20d90 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71  recent failed sq
20da0 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
20db0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
20dc0 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
20dd0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20  connection]. If 
20de0 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c  a prior API call
20df0 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74   failed.** but t
20e00 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  he most recent A
20e10 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65  PI call succeede
20e20 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  d, the return va
20e30 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  lue from.** sqli
20e40 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
20e50 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   undefined.  ^Th
20e60 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
20e70 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  ed_errcode().** 
20e80 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65  interface is the
20e90 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61   same except tha
20ea0 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  t it always retu
20eb0 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74  rns the .** [ext
20ec0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
20ed0 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74  e] even when ext
20ee0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
20ef0 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  es are.** disabl
20f00 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
20f10 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
20f20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
20f30 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
20f40 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
20f50 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
20f60 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
20f70 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
20f80 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
20f90 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65  ctively..** ^(Me
20fa0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
20fb0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
20fc0 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
20fd0 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
20fe0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
20ff0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
21000 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
21010 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
21020 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
21030 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
21040 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
21050 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
21060 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
21070 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
21080 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
21090 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a  ce functions.)^.
210a0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73  **.** When the s
210b0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
210c0 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e  ding mode] is in
210d0 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62   use, it might b
210e0 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68  e the.** case th
210f0 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f  at a second erro
21100 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65  r occurs on a se
21110 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e  parate thread in
21120 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
21130 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73  time of the firs
21140 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20  t error and the 
21150 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e  call to these in
21160 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65  terfaces..** Whe
21170 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20  n that happens, 
21180 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  the second error
21190 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65   will be reporte
211a0 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a  d since these.**
211b0 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61   interfaces alwa
211c0 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f  ys report the mo
211d0 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74  st recent result
211e0 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74  .  To avoid.** t
211f0 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64  his, each thread
21200 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c   can obtain excl
21210 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65  usive use of the
21220 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
21230 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69  ction] D.** by i
21240 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
21250 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73  _mutex_enter]([s
21260 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
21270 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69  (D)) before begi
21280 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20  nning.** to use 
21290 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b  D and invoking [
212a0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
212b0 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ave]([sqlite3_db
212c0 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65  _mutex](D)) afte
212d0 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74  r.** all calls t
212e0 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73  o the interfaces
212f0 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65   listed here are
21300 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a   completed..**.*
21310 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63  * If an interfac
21320 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c  e fails with SQL
21330 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74  ITE_MISUSE, that
21340 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72   means the inter
21350 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f  face.** was invo
21360 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ked incorrectly 
21370 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
21380 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73  on.  In that cas
21390 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20  e, the.** error 
213a0 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
213b0 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20   may or may not 
213c0 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73  be set..*/.int s
213d0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73  qlite3_errcode(s
213e0 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74  qlite3 *db);.int
213f0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
21400 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  d_errcode(sqlite
21410 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68  3 *db);.const ch
21420 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  ar *sqlite3_errm
21430 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f  sg(sqlite3*);.co
21440 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
21450 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74  3_errmsg16(sqlit
21460 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
21470 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65  I3REF: SQL State
21480 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  ment Object.** K
21490 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
214a0 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
214b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
214c0 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
214d0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
214e0 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
214f0 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
21500 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20  tement..** This 
21510 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75  object is variou
21520 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22  sly known as a "
21530 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21540 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d  nt" or a.** "com
21550 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
21560 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61  ent" or simply a
21570 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e  s a "statement".
21580 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20  .**.** The life 
21590 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f  of a statement o
215a0 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74  bject goes somet
215b0 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a  hing like this:.
215c0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
215d0 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62  i> Create the ob
215e0 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
215f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
21600 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a  ] or a related.*
21610 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e  *      function.
21620 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
21630 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61  lues to [host pa
21640 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20  rameters] using 
21650 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
21660 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74  _*().**      int
21670 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  erfaces..** <li>
21680 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20   Run the SQL by 
21690 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
216a0 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20  _step()] one or 
216b0 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
216c0 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74  li> Reset the st
216d0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
216e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
216f0 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
21700 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
21710 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
21720 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
21730 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
21740 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
21750 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
21760 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  )]..** </ol>.**.
21770 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75  ** Refer to docu
21780 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  mentation on ind
21790 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20  ividual methods 
217a0 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69  above for additi
217b0 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
217c0 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
217d0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
217e0 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
217f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
21800 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
21810 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  ts.**.** ^(This 
21820 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
21830 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
21840 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
21850 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
21860 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
21870 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
21880 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
21890 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
218a0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
218b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
218c0 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
218d0 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
218e0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
218f0 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
21900 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
21910 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
21920 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
21930 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
21940 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
21950 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
21960 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
21970 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
21980 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29  that construct.)
21990 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ^.**.** ^If the 
219a0 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e  new limit is a n
219b0 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20  egative number, 
219c0 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63  the limit is unc
219d0 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72  hanged..** ^(For
219e0 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65   each limit cate
219f0 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49  gory SQLITE_LIMI
21a00 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68  T_<i>NAME</i> th
21a10 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69  ere is a .** [li
21a20 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65  mits | hard uppe
21a30 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20  r bound].** set 
21a40 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
21a50 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73  by a C preproces
21a60 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64  sor macro called
21a70 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51  .** [limits | SQ
21a80 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45  LITE_MAX_<i>NAME
21a90 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22  </i>]..** (The "
21aa0 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20  _LIMIT_" in the 
21ab0 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20  name is changed 
21ac0 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a  to "_MAX_".))^.*
21ad0 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69  * ^Attempts to i
21ae0 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20  ncrease a limit 
21af0 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75  above its hard u
21b00 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a  pper bound are.*
21b10 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  * silently trunc
21b20 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64  ated to the hard
21b30 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a   upper bound..**
21b40 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20  .** ^Regardless 
21b50 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
21b60 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20  t the limit was 
21b70 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a  changed, the .**
21b80 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
21b90 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
21ba0 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76  urns the prior v
21bb0 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69  alue of the limi
21bc0 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f  t..** ^Hence, to
21bd0 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e   find the curren
21be0 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d  t value of a lim
21bf0 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  it without chang
21c00 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c  ing it,.** simpl
21c10 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e  y invoke this in
21c20 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65  terface with the
21c30 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
21c40 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a   set to -1..**.*
21c50 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  * Run-time limit
21c60 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
21c70 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
21c80 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
21c90 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
21ca0 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
21cb0 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
21cc0 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
21cd0 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
21ce0 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
21cf0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
21d00 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
21d10 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
21d20 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65   a.** web browse
21d30 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f  r that has its o
21d40 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72  wn databases for
21d50 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79   storing history
21d60 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65   and.** separate
21d70 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72   databases contr
21d80 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72  olled by JavaScr
21d90 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ipt applications
21da0 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f   downloaded.** o
21db0 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e  ff the Internet.
21dc0 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
21dd0 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
21de0 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
21df0 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
21e00 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
21e10 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
21e20 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
21e30 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
21e40 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
21e50 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
21e60 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
21e70 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b  ervice.** attack
21e80 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69  .  Developers mi
21e90 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f  ght also want to
21ea0 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
21eb0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
21ec0 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
21ed0 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74   to further cont
21ee0 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51  rol untrusted SQ
21ef0 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  L.  The size of 
21f00 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
21f10 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e  created by an un
21f20 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63  trusted script c
21f30 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  an be contained 
21f40 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61  using the.** [ma
21f50 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
21f60 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65  RAGMA]..**.** Ne
21f70 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  w run-time limit
21f80 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20   categories may 
21f90 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
21fa0 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a  re releases..*/.
21fb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69  int sqlite3_limi
21fc0 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
21fd0 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b  id, int newVal);
21fe0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21ff0 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74  : Run-Time Limit
22000 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b   Categories.** K
22010 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20  EYWORDS: {limit 
22020 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69  category} {*limi
22030 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a  t categories}.**
22040 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
22050 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
22060 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c  us performance l
22070 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61  imits.** that ca
22080 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20  n be lowered at 
22090 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b  run-time using [
220a0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
220b0 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69  ..** The synopsi
220c0 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67  s of the meaning
220d0 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73  s of the various
220e0 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e   limits is shown
220f0 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74   below..** Addit
22100 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
22110 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61  n is available a
22120 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69  t [limits | Limi
22130 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a  ts in SQLite]..*
22140 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
22150 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
22160 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
22170 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f  E_LIMIT_LENGTH</
22180 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
22190 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61  aximum size of a
221a0 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f  ny string or BLO
221b0 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20  B or table row, 
221c0 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a  in bytes.<dd>)^.
221d0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
221e0 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d  IMIT_SQL_LENGTH]
221f0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
22200 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c  IMIT_SQL_LENGTH<
22210 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
22220 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
22230 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
22240 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64  nt, in bytes.</d
22250 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
22260 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
22270 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
22280 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74  LIMIT_COLUMN</dt
22290 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
222a0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
222b0 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c  olumns in a tabl
222c0 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20  e definition or 
222d0 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  in the.** result
222e0 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
222f0 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75  T] or the maximu
22300 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
22310 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
22320 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45  ** or in an ORDE
22330 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59  R BY or GROUP BY
22340 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a   clause.</dd>)^.
22350 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
22360 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d  IMIT_EXPR_DEPTH]
22370 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
22380 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c  IMIT_EXPR_DEPTH<
22390 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
223a0 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
223b0 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20   the parse tree 
223c0 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f  on any expressio
223d0 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
223e0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
223f0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d  OMPOUND_SELECT]]
22400 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
22410 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
22420 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ECT</dt>.** <dd>
22430 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
22440 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61  er of terms in a
22450 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
22460 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
22470 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
22480 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d  E_LIMIT_VDBE_OP]
22490 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
224a0 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74  IMIT_VDBE_OP</dt
224b0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
224c0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69  imum number of i
224d0 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61  nstructions in a
224e0 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
224f0 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64   program.** used
22500 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e   to implement an
22510 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
22520 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e   This limit is n
22530 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20  ot currently.** 
22540 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68  enforced, though
22550 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61   that might be a
22560 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74  dded in some fut
22570 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
22580 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e  * SQLite.</dd>)^
22590 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
225a0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
225b0 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  RG]] ^(<dt>SQLIT
225c0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
225d0 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _ARG</dt>.** <dd
225e0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
225f0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
22600 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c   on a function.<
22610 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
22620 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
22630 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  CHED]] ^(<dt>SQL
22640 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
22650 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
22660 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
22670 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61  r of [ATTACH | a
22680 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
22690 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s].)^</dd>.**.**
226a0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
226b0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
226c0 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53  GTH]].** ^(<dt>S
226d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
226e0 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c  _PATTERN_LENGTH<
226f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
22700 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
22710 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72  f the pattern ar
22720 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c  gument to the [L
22730 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42  IKE] or.** [GLOB
22740 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64  ] operators.</dd
22750 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
22760 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
22770 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28  E_NUMBER]].** ^(
22780 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
22790 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
227a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
227b0 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e   maximum index n
227c0 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61  umber of any [pa
227d0 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53  rameter] in an S
227e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a  QL statement.)^.
227f0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
22800 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
22810 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
22820 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
22830 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
22840 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
22850 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e  pth of recursion
22860 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f   for triggers.</
22870 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
22880 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22890 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
228a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
228b0 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
228c0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
228d0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
228e0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
228f0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
22900 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22910 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
22920 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
22930 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
22940 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
22950 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
22960 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
22970 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
22980 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
22990 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
229a0 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
229b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
229c0 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
229d0 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
229e0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
229f0 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
22a00 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
22a10 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
22a20 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
22a30 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
22a40 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
22a50 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
22a60 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
22a70 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
22a80 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20  _TRIGGER_DEPTH  
22a90 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a            10../*
22aa0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
22ab0 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
22ac0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57  tatement.** KEYW
22ad0 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65  ORDS: {SQL state
22ae0 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a  ment compiler}.*
22af0 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
22b00 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74  an SQL query, it
22b10 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
22b20 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
22b30 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
22b40 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
22b50 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
22b60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
22b70 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c   argument, "db",
22b80 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
22b90 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61  connection] obta
22ba0 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70  ined from a.** p
22bb0 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
22bc0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
22bd0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
22be0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72  e3_open_v2()] or
22bf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
22c00 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74  n16()].  The dat
22c10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22c20 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62   must not have b
22c30 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a  een closed..**.*
22c40 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
22c50 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69  ument, "zSql", i
22c60 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
22c70 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
22c80 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
22c90 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
22ca0 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
22cb0 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
22cc0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
22cd0 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v2().** interfa
22ce0 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61  ces use UTF-8, a
22cf0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
22d00 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74  re16() and sqlit
22d10 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
22d20 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e  ).** use UTF-16.
22d30 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
22d40 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
22d50 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c   less than zero,
22d60 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
22d70 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20  ad up to the.** 
22d80 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
22d90 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65  nator. ^If nByte
22da0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
22db0 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65  , then it is the
22dc0 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62   maximum.** numb
22dd0 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61  er of  bytes rea
22de0 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57  d from zSql.  ^W
22df0 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  hen nByte is non
22e00 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a  -negative, the.*
22e10 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e  * zSql string en
22e20 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65  ds at either the
22e30 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72   first '\000' or
22e40 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63   '\u0000' charac
22e50 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42  ter or.** the nB
22e60 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69  yte-th byte, whi
22e70 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
22e80 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65  st. If the calle
22e90 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20  r knows.** that 
22ea0 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72  the supplied str
22eb0 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69  ing is nul-termi
22ec0 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72  nated, then ther
22ed0 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20  e is a small.** 
22ee0 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61  performance adva
22ef0 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e  ntage to be gain
22f00 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e  ed by passing an
22f10 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72   nByte parameter
22f20 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61   that.** is equa
22f30 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20  l to the number 
22f40 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
22f50 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e  input string <i>
22f60 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a  including</i>.**
22f70 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61   the nul-termina
22f80 74 6f 72 20 62 79 74 65 73 20 61 73 20 74 68 69  tor bytes as thi
22f90 73 20 73 61 76 65 73 20 53 51 4c 69 74 65 20 66  s saves SQLite f
22fa0 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a  rom having to.**
22fb0 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20   make a copy of 
22fc0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
22fd0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61  ..**.** ^If pzTa
22fe0 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  il is not NULL t
22ff0 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  hen *pzTail is m
23000 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
23010 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a  the first byte.*
23020 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  * past the end o
23030 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20  f the first SQL 
23040 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
23050 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  l.  These routin
23060 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69  es only.** compi
23070 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61  le the first sta
23080 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
23090 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
230a0 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a  ft pointing to.*
230b0 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75  * what remains u
230c0 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
230d0 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66   ^*ppStmt is lef
230e0 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20  t pointing to a 
230f0 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72  compiled [prepar
23100 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
23110 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65  at can be.** exe
23120 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cuted using [sql
23130 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e  ite3_step()].  ^
23140 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65  If there is an e
23150 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73  rror, *ppStmt is
23160 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e   set.** to NULL.
23170 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20    ^If the input 
23180 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
23190 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
231a0 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a  ut is an empty.*
231b0 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  * string or a co
231c0 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
231d0 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
231e0 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69  LL..** The calli
231f0 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
23200 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
23210 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d  deleting the com
23220 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  piled.** SQL sta
23230 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
23240 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
23250 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  ] after it has f
23260 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
23270 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e  .** ppStmt may n
23280 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ot be NULL..**.*
23290 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74  * ^On success, t
232a0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
232b0 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72  re() family of r
232c0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
232d0 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f  SQLITE_OK];.** o
232e0 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
232f0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
23300 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
23310 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
23320 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  v2() and sqlite3
23330 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20  _prepare16_v2() 
23340 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a  interfaces are.*
23350 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  * recommended fo
23360 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61  r all new progra
23370 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65  ms. The two olde
23380 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  r interfaces are
23390 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72   retained.** for
233a0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
233b0 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68  tibility, but th
233c0 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f  eir use is disco
233d0 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74  uraged..** ^In t
233e0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
233f0 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
23400 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
23410 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
23420 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
23430 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
23440 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
23450 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
23460 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
23470 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
23480 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
23490 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
234a0 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
234b0 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  hree ways:.**.**
234c0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
234d0 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
234e0 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73  e schema changes
234f0 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74  , instead of ret
23500 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53  urning [SQLITE_S
23510 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20  CHEMA] as it.** 
23520 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64  always used to d
23530 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  o, [sqlite3_step
23540 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ()] will automat
23550 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
23560 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74   the SQL.** stat
23570 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f  ement and try to
23580 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a   run it again..*
23590 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
235a0 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65  i>.** ^When an e
235b0 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71  rror occurs, [sq
235c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
235d0 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
235e0 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a   the detailed.**
235f0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
23600 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
23610 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20  r codes].  ^The 
23620 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
23630 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
23640 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
23650 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
23660 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
23670 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
23680 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61  ode.** and the a
23690 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64  pplication would
236a0 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
236b0 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b  second call to [
236c0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
236d0 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  .** in order to 
236e0 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
236f0 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
23700 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74   problem. With t
23710 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a  he "v2" prepare.
23720 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  ** interfaces, t
23730 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
23740 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
23750 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  or is returned i
23760 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
23770 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
23780 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
23790 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20  fic value bound 
237a0 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20  to [parameter | 
237b0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20  host parameter] 
237c0 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45  in the .** WHERE
237d0 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e   clause might in
237e0 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69  fluence the choi
237f0 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
23800 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74   for a statement
23810 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74  ,.** then the st
23820 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  atement will be 
23830 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
23840 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20  compiled, as if 
23850 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a  there had been .
23860 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  ** a schema chan
23870 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ge, on the first
23880 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28    [sqlite3_step(
23890 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e  )] call followin
238a0 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20  g any change.** 
238b0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
238c0 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64  bind_text | bind
238d0 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70  ings] of that [p
238e0 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e  arameter]. .** ^
238f0 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  The specific val
23900 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75  ue of WHERE-clau
23910 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d  se [parameter] m
23920 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
23930 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66  he .** choice of
23940 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74   query plan if t
23950 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
23960 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69  the left-hand si
23970 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a  de of a [LIKE].*
23980 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  * or [GLOB] oper
23990 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70  ator or if the p
239a0 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70  arameter is comp
239b0 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78  ared to an index
239c0 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64  ed column.** and
239d0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41   the [SQLITE_ENA
239e0 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69  BLE_STAT3] compi
239f0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
23a00 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68  s enabled..** th
23a10 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  e .** </li>.** <
23a20 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  /ol>.*/.int sqli
23a30 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
23a40 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
23a50 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
23a60 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
23a70 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
23a80 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
23a90 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
23aa0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
23ab0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
23ac0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
23ad0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
23ae0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
23af0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
23b00 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
23b10 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
23b20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
23b30 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
23b40 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
23b50 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
23b60 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
23b70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
23b80 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
23b90 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
23ba0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
23bb0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
23bc0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
23bd0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
23be0 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
23bf0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
23c00 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
23c10 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
23c20 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
23c30 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
23c40 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
23c50 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
23c60 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
23c70 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
23c80 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
23c90 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
23ca0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
23cb0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
23cc0 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
23cd0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
23ce0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
23cf0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
23d00 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
23d10 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
23d20 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
23d30 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
23d40 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
23d50 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
23d60 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
23d70 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
23d80 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
23d90 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
23da0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
23db0 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
23dc0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
23dd0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
23de0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
23df0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
23e00 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
23e10 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
23e20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
23e30 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
23e40 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
23e50 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
23e60 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
23e70 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
23e80 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
23e90 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
23ea0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
23eb0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
23ec0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
23ed0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
23ee0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
23ef0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
23f00 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
23f10 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
23f20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
23f30 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
23f40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23f50 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
23f60 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20  ement SQL.**.** 
23f70 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
23f80 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
23f90 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20  etrieve a saved 
23fa0 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67  copy of the orig
23fb0 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74  inal.** SQL text
23fc0 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20   used to create 
23fd0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
23fe0 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73  ement] if that s
23ff0 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20  tatement was.** 
24000 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
24010 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
24020 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
24030 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
24040 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  16_v2()]..*/.con
24050 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
24060 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
24070 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
24080 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
24090 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
240a0 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73  Statement Writes
240b0 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a   The Database.**
240c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
240d0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58  _stmt_readonly(X
240e0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
240f0 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
24100 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e  ro) if.** and on
24110 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61  ly if the [prepa
24120 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58  red statement] X
24130 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74   makes no direct
24140 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74   changes to.** t
24150 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
24160 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  e database file.
24170 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
24180 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
24190 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
241a0 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74  ons] or.** [virt
241b0 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68  ual tables] migh
241c0 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
241d0 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79  abase indirectly
241e0 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63   as a side effec
241f0 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  t.  .** ^(For ex
24200 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70  ample, if an app
24210 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73  lication defines
24220 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61   a function "eva
24230 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61  l()" that .** ca
24240 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  lls [sqlite3_exe
24250 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66  c()], then the f
24260 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61  ollowing SQL sta
24270 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20  tement would.** 
24280 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
24290 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68  ase file through
242a0 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a   side-effects:.*
242b0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
242c0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c  ><pre>.**    SEL
242d0 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45  ECT eval('DELETE
242e0 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20   FROM t1') FROM 
242f0 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  t2;.** </pre></b
24300 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
24310 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65   But because the
24320 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
24330 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ent does not cha
24340 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
24350 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c   file.** directl
24360 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  y, sqlite3_stmt_
24370 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64  readonly() would
24380 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72   still return tr
24390 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61  ue.)^.**.** ^Tra
243a0 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
243b0 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68   statements such
243c0 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f   as [BEGIN], [CO
243d0 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b  MMIT], [ROLLBACK
243e0 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54  ],.** [SAVEPOINT
243f0 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d  ], and [RELEASE]
24400 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73   cause sqlite3_s
24410 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
24420 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a  o return true,.*
24430 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74  * since the stat
24440 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65  ements themselve
24450 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c  s do not actuall
24460 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  y modify the dat
24470 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74  abase but.** rat
24480 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c  her they control
24490 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77   the timing of w
244a0 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d  hen other statem
244b0 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20  ents modify the 
244c0 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e  .** database.  ^
244d0 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64  The [ATTACH] and
244e0 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d   [DETACH] statem
244f0 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a  ents also cause.
24500 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  ** sqlite3_stmt_
24510 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
24520 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c  turn true since,
24530 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61   while those sta
24540 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67  tements.** chang
24550 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  e the configurat
24560 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73  ion of a databas
24570 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68  e connection, th
24580 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a  ey do not make .
24590 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ** changes to th
245a0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
245b0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
245c0 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20  on disk..*/.int 
245d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
245e0 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74  donly(sqlite3_st
245f0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
24600 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
24610 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70  ermine If A Prep
24620 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48  ared Statement H
24630 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a  as Been Reset.**
24640 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
24650 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e  _stmt_busy(S) in
24660 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
24670 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
24680 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  if the.** [prepa
24690 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
246a0 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65   has been steppe
246b0 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20  d at least once 
246c0 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
246d0 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20  e3_step(S)] but 
246e0 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63  has not run to c
246f0 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72  ompletion and/or
24700 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65   has not .** bee
24710 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73  n reset using [s
24720 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
24730 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
24740 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20  stmt_busy(S).** 
24750 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
24760 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20  s false if S is 
24770 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
24780 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a   If S is not a .
24790 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
247a0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69  and is not a poi
247b0 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20  nter to a valid 
247c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
247d0 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20  ent].** object, 
247e0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
247f0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  r is undefined a
24800 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
24810 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54  sirable..**.** T
24820 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
24830 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d  n be used in com
24840 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65  bination [sqlite
24850 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a  3_next_stmt()].*
24860 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20  * to locate all 
24870 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24880 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  nts associated w
24890 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a  ith a database .
248a0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
248b0 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f  at are in need o
248c0 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20  f being reset.  
248d0 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64  This can be used
248e0 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65  ,.** for example
248f0 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20  , in diagnostic 
24900 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72  routines to sear
24910 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20  ch for prepared 
24920 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74  .** statements t
24930 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20  hat are holding 
24940 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70  a transaction op
24950 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  en..*/.int sqlit
24960 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c  e3_stmt_busy(sql
24970 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
24980 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79  .** CAPI3REF: Dy
24990 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20  namically Typed 
249a0 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  Value Object.** 
249b0 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65  KEYWORDS: {prote
249c0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
249d0 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64  ue} {unprotected
249e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a   sqlite3_value}.
249f0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
24a00 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61  s the sqlite3_va
24a10 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65  lue object to re
24a20 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75  present all valu
24a30 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  es.** that can b
24a40 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61  e stored in a da
24a50 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51  tabase table. SQ
24a60 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
24a70 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20  c typing.** for 
24a80 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74  the values it st
24a90 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73  ores.  ^Values s
24aa0 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33  tored in sqlite3
24ab0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a  _value objects.*
24ac0 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72  * can be integer
24ad0 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  s, floating poin
24ae0 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
24af0 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
24b00 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69  L..**.** An sqli
24b10 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
24b20 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22   may be either "
24b30 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75  protected" or "u
24b40 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20  nprotected"..** 
24b50 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20  Some interfaces 
24b60 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63  require a protec
24b70 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
24b80 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66  e.  Other interf
24b90 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63  aces.** will acc
24ba0 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f  ept either a pro
24bb0 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70  tected or an unp
24bc0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
24bd0 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79  _value..** Every
24be0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
24bf0 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f  accepts sqlite3_
24c00 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20  value arguments 
24c10 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65  specifies.** whe
24c20 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72  ther or not it r
24c30 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63  equires a protec
24c40 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
24c50 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72  e..**.** The ter
24c60 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61  ms "protected" a
24c70 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  nd "unprotected"
24c80 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65   refer to whethe
24c90 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  r or not.** a mu
24ca0 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e  tex is held.  An
24cb0 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   internal mutex 
24cc0 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72  is held for a pr
24cd0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
24ce0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
24cf0 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20  but no mutex is 
24d00 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72  held for an unpr
24d10 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
24d20 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e  e3_value object.
24d30 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
24d40 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69  ompiled to be si
24d50 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ngle-threaded.**
24d60 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54   (with [SQLITE_T
24d70 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64  HREADSAFE=0] and
24d80 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74   with [sqlite3_t
24d90 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74  hreadsafe()] ret
24da0 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20  urning 0).** or 
24db0 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e  if SQLite is run
24dc0 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63   in one of reduc
24dd0 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a  ed mutex modes .
24de0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
24df0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20  G_SINGLETHREAD] 
24e00 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
24e10 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a  G_MULTITHREAD].*
24e20 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  * then there is 
24e30 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  no distinction b
24e40 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
24e50 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
24e60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
24e70 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68  e objects and th
24e80 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ey can be used i
24e90 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20  nterchangeably. 
24ea0 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72   However,.** for
24eb0 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f   maximum code po
24ec0 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20  rtability it is 
24ed0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
24ee0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
24ef0 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20   still make the 
24f00 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
24f10 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
24f20 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
24f30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
24f40 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e  bjects even when
24f50 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65   not strictly re
24f60 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  quired..**.** ^T
24f70 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
24f80 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72   objects that ar
24f90 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61  e passed as para
24fa0 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a  meters into the.
24fb0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
24fc0 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f  n of [applicatio
24fd0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
24fe0 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f  nctions] are pro
24ff0 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  tected..** ^The 
25000 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
25010 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
25020 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
25030 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
25040 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  unprotected..** 
25050 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  Unprotected sqli
25060 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
25070 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  s may only be us
25080 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69  ed with.** [sqli
25090 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
250a0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
250b0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a  _bind_value()]..
250c0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
250d0 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c  value_blob | sql
250e0 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
250f0 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  )] family of.** 
25100 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
25110 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  re protected sql
25120 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
25130 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ts..*/.typedef s
25140 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65  truct Mem sqlite
25150 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20  3_value;../*.** 
25160 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75  CAPI3REF: SQL Fu
25170 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f  nction Context O
25180 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
25190 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68  context in which
251a0 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
251b0 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f   executes is sto
251c0 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c  red in an.** sql
251d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
251e0 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72  ect.  ^A pointer
251f0 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63   to an sqlite3_c
25200 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a  ontext object.**
25210 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74   is always first
25220 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61   parameter to [a
25230 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
25240 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
25250 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  ]..** The applic
25260 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
25270 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
25280 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70  mentation will p
25290 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e  ass this.** poin
252a0 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f  ter through into
252b0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
252c0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20  e3_result_int | 
252d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29  sqlite3_result()
252e0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61  ],.** [sqlite3_a
252f0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
25300 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73  ()], [sqlite3_us
25310 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b  er_data()],.** [
25320 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
25330 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73  db_handle()], [s
25340 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
25350 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ta()],.** and/or
25360 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
25370 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70  xdata()]..*/.typ
25380 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
25390 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69  te3_context sqli
253a0 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a  te3_context;../*
253b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69  .** CAPI3REF: Bi
253c0 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20  nding Values To 
253d0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
253e0 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  nts.** KEYWORDS:
253f0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
25400 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
25410 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  rs} {host parame
25420 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59  ter name}.** KEY
25430 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61  WORDS: {SQL para
25440 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61  meter} {SQL para
25450 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74  meters} {paramet
25460 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a  er binding}.**.*
25470 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73  * ^(In the SQL s
25480 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e  tatement text in
25490 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
254a0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
254b0 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a  d its variants,.
254c0 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20  ** literals may 
254d0 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  be replaced by a
254e0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61   [parameter] tha
254f0 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66  t matches one of
25500 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65   following.** te
25510 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  mplates:.**.** <
25520 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
25530 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
25540 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
25550 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
25560 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
25570 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d  **.** In the tem
25580 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e  plates above, NN
25590 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  N represents an 
255a0 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
255b0 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72  .** and VVV repr
255c0 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e  esents an alphan
255d0 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65  umeric identifie
255e0 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65  r.)^  ^The value
255f0 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61  s of these.** pa
25600 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
25610 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
25620 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20  meter names" or 
25630 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22  "SQL parameters"
25640 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20  ).** can be set 
25650 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
25660 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
25670 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65  nes defined here
25680 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
25690 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
256a0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
256b0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20  *() routines is 
256c0 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e  always.** a poin
256d0 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
256e0 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
256f0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
25700 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
25710 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
25720 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  variants..**.** 
25730 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
25740 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
25750 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
25760 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
25770 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ..** ^The leftmo
25780 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
25790 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
257a0 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73   1.  ^When the s
257b0 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c  ame named.** SQL
257c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
257d0 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
257e0 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
257f0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
25800 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
25810 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
25820 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
25830 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64  nce..** ^The ind
25840 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
25850 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
25860 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
25870 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
25880 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
25890 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65  dex()] API if de
258a0 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64  sired.  ^The ind
258b0 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
258c0 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
258d0 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
258e0 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c  .** ^The NNN val
258f0 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
25900 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71  en 1 and the [sq
25910 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
25920 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c  * parameter [SQL
25930 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
25940 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61  LE_NUMBER] (defa
25950 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
25960 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
25970 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
25980 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
25990 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
259a0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f  ..**.** ^(In tho
259b0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  se routines that
259c0 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
259d0 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
259e0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
259f0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
25a00 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
25a10 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
25a20 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
25a30 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
25a40 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76  tes</u> in the v
25a50 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
25a60 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
25a70 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65  rs.)^.** ^If the
25a80 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
25a90 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
25aa0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
25ab0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68   string is.** th
25ac0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
25ad0 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  s up to the firs
25ae0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
25af0 72 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e  r..** If a non-n
25b00 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70  egative fourth p
25b10 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76  arameter is prov
25b20 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f  ided to sqlite3_
25b30 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f  bind_text().** o
25b40 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
25b50 65 78 74 31 36 28 29 20 74 68 65 6e 20 74 68 61  ext16() then tha
25b60 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
25b70 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66   be the byte off
25b80 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65  set.** where the
25b90 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20   NUL terminator 
25ba0 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75  would occur assu
25bb0 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20  ming the string 
25bc0 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d  were NUL.** term
25bd0 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20  inated.  If any 
25be0 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f  NUL characters o
25bf0 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66  ccur at byte off
25c00 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a  sets less than .
25c10 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ** the value of 
25c20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
25c30 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65  eter then the re
25c40 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76  sulting string v
25c50 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  alue will.** con
25c60 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55  tain embedded NU
25c70 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  Ls.  The result 
25c80 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69  of expressions i
25c90 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73  nvolving strings
25ca0 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65  .** with embedde
25cb0 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
25cc0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
25cd0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74  fifth argument t
25ce0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
25cf0 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62  lob(), sqlite3_b
25d00 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a  ind_text(), and.
25d10 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ** sqlite3_bind_
25d20 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65  text16() is a de
25d30 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f  structor used to
25d40 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
25d50 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e  BLOB or.** strin
25d60 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68  g after SQLite h
25d70 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
25d80 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72   it.  ^The destr
25d90 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a  uctor is called.
25da0 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ** to dispose of
25db0 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72   the BLOB or str
25dc0 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
25dd0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
25de0 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20  bind_blob(),.** 
25df0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
25e00 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  t(), or sqlite3_
25e10 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61  bind_text16() fa
25e20 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68  ils.  .** ^If th
25e30 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
25e40 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69   is.** the speci
25e50 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  al value [SQLITE
25e60 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53  _STATIC], then S
25e70 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
25e80 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d  at the.** inform
25e90 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74  ation is in stat
25ea0 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  ic, unmanaged sp
25eb0 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
25ec0 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65   need to be free
25ed0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  d..** ^If the fi
25ee0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73  fth argument has
25ef0 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49   the value [SQLI
25f00 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
25f10 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  hen.** SQLite ma
25f20 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76  kes its own priv
25f30 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
25f40 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79  data immediately
25f50 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20  , before.** the 
25f60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
25f70 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
25f80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
25f90 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
25fa0 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e  ob() routine bin
25fb0 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e  ds a BLOB of len
25fc0 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73  gth N that.** is
25fd0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72   filled with zer
25fe0 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f  oes.  ^A zeroblo
25ff0 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
26000 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
26010 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
26020 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20  ger to hold its 
26030 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
26040 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
26050 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
26060 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
26070 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f  serve as placeho
26080 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
26090 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
260a0 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
260b0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
260c0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
260d0 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
260e0 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a   I/O] routines..
260f0 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76  ** ^A negative v
26100 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72  alue for the zer
26110 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e  oblob results in
26120 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
26130 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  LOB..**.** ^If a
26140 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ny of the sqlite
26150 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
26160 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77  nes are called w
26170 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
26180 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70  er.** for the [p
26190 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
261a0 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65  t] or with a pre
261b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
261c0 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71  for which.** [sq
261d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
261e0 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f  s been called mo
261f0 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e  re recently than
26200 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
26210 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  )],.** then the 
26220 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e  call will return
26230 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
26240 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65  .  If any sqlite
26250 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75  3_bind_().** rou
26260 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61  tine is passed a
26270 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26280 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62  ment] that has b
26290 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74  een finalized, t
262a0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20  he.** result is 
262b0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
262c0 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a  obably harmful..
262d0 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20  **.** ^Bindings 
262e0 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
262f0 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
26300 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
26310 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61  ..** ^Unbound pa
26320 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74  rameters are int
26330 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c  erpreted as NULL
26340 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
26350 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74  ite3_bind_* rout
26360 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
26370 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
26380 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72  ss or an.** [err
26390 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74  or code] if anyt
263a0 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
263b0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e  .** ^[SQLITE_RAN
263c0 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  GE] is returned 
263d0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
263e0 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74  .** index is out
263f0 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51   of range.  ^[SQ
26400 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72  LITE_NOMEM] is r
26410 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f  eturned if mallo
26420 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  c() fails..**.**
26430 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
26440 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
26450 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20  er_count()],.** 
26460 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
26470 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
26480 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
26490 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
264a0 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
264b0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
264c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
264d0 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
264e0 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
264f0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
26500 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65  ite3_bind_double
26510 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
26520 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e  int, double);.in
26530 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
26540 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
26550 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74  , int, int);.int
26560 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
26570 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
26580 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
26590 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69  int64);.int sqli
265a0 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71  te3_bind_null(sq
265b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
265c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
265d0 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ind_text(sqlite3
265e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
265f0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c  st char*, int n,
26600 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
26610 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
26620 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
26630 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
26640 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
26650 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
26660 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
26670 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
26680 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
26690 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
266a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
266b0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ind_zeroblob(sql
266c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
266d0 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
266e0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
266f0 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65   Of SQL Paramete
26700 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  rs.**.** ^This r
26710 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73  outine can be us
26720 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
26730 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61  umber of [SQL pa
26740 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20  rameters].** in 
26750 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
26760 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72  ement].  SQL par
26770 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65  ameters are toke
26780 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72  ns of the.** for
26790 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22  m "?", "?NNN", "
267a0 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f  :AAA", "$AAA", o
267b0 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65  r "@AAA" that se
267c0 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68  rve as.** placeh
267d0 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65  olders for value
267e0 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69  s that are [sqli
267f0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
26800 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65  bound].** to the
26810 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61   parameters at a
26820 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a   later time..**.
26830 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e  ** ^(This routin
26840 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72  e actually retur
26850 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  ns the index of 
26860 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67  the largest (rig
26870 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d  htmost).** param
26880 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f  eter. For all fo
26890 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c  rms except ?NNN,
268a0 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65   this will corre
268b0 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20  spond to the.** 
268c0 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65  number of unique
268d0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66   parameters.  If
268e0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
268f0 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65  he ?NNN form are
26900 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20   used,.** there 
26910 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74  may be gaps in t
26920 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a  he list.)^.**.**
26930 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
26940 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
26950 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
26960 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
26970 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
26980 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
26990 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
269a0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
269b0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
269c0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
269d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
269e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
269f0 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20   Name Of A Host 
26a00 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20  Parameter.**.** 
26a10 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
26a20 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
26a30 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (P,N) interface 
26a40 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
26a50 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20  ame of the N-th 
26a60 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
26a70 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
26a80 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
26a90 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65  * ^(SQL paramete
26aa0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
26ab0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
26ac0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
26ad0 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61  AA".** have a na
26ae0 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20  me which is the 
26af0 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72  string "?NNN" or
26b00 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
26b10 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72  " or "$AAA".** r
26b20 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
26b30 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
26b40 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20  the initial ":" 
26b50 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72  or "$" or "@" or
26b60 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75   "?".** is inclu
26b70 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  ded as part of t
26b80 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50  he name.)^.** ^P
26b90 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
26ba0 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75   form "?" withou
26bb0 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  t a following in
26bc0 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61  teger have no na
26bd0 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65  me.** and are re
26be0 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61  ferred to as "na
26bf0 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e  meless" or "anon
26c00 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73  ymous parameters
26c10 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  "..**.** ^The fi
26c20 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74  rst host paramet
26c30 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
26c40 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a  of 1, not 0..**.
26c50 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65  ** ^If the value
26c60 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   N is out of ran
26c70 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74  ge or if the N-t
26c80 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
26c90 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e  * nameless, then
26ca0 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
26cb0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  d.  ^The returne
26cc0 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61  d string is.** a
26cd0 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65  lways in UTF-8 e
26ce0 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20  ncoding even if 
26cf0 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  the named parame
26d00 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69  ter was.** origi
26d10 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20  nally specified 
26d20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71  as UTF-16 in [sq
26d30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
26d40 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
26d50 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
26d60 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
26d70 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
26d80 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
26d90 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
26da0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
26db0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
26dc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
26dd0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
26de0 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
26df0 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64  ar *sqlite3_bind
26e00 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
26e10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
26e20 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
26e30 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41  3REF: Index Of A
26e40 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20   Parameter With 
26e50 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a  A Given Name.**.
26e60 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69  ** ^Return the i
26e70 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
26e80 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69  arameter given i
26e90 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a  ts name.  ^The.*
26ea0 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65  * index value re
26eb0 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62  turned is suitab
26ec0 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68  le for use as th
26ed0 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61  e second.** para
26ee0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
26ef0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
26f00 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41  te3_bind()].  ^A
26f10 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75   zero.** is retu
26f20 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68  rned if no match
26f30 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  ing parameter is
26f40 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61   found.  ^The pa
26f50 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20  rameter.** name 
26f60 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e  must be given in
26f70 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74   UTF-8 even if t
26f80 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
26f90 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65  ement.** was pre
26fa0 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31  pared from UTF-1
26fb0 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71  6 text using [sq
26fc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
26fd0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
26fe0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
26ff0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
27000 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
27010 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
27020 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
27030 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
27040 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
27050 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
27060 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
27070 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
27080 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
27090 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
270a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
270b0 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
270c0 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
270d0 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d Statement.**.*
270e0 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74  * ^Contrary to t
270f0 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20  he intuition of 
27100 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72  many, [sqlite3_r
27110 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74  eset()] does not
27120 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73   reset.** the [s
27130 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
27140 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20   | bindings] on 
27150 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
27160 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20  ement]..** ^Use 
27170 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
27180 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
27190 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
271a0 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  L..*/.int sqlite
271b0 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
271c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
271d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
271e0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75  : Number Of Colu
271f0 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mns In A Result 
27200 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  Set.**.** ^Retur
27210 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
27220 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
27230 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e  esult set return
27240 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72  ed by the.** [pr
27250 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27260 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ]. ^This routine
27270 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53   returns 0 if pS
27280 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a  tmt is an SQL.**
27290 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
272a0 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20  does not return 
272b0 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c  data (for exampl
272c0 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a  e an [UPDATE])..
272d0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
272e0 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
272f0 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71  unt()].*/.int sq
27300 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
27310 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
27320 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
27330 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e  CAPI3REF: Column
27340 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75   Names In A Resu
27350 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  lt Set.**.** ^Th
27360 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
27370 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
27380 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
27390 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
273a0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
273b0 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
273c0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65  statement.  ^The
273d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
273e0 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
273f0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
27400 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
27410 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
27420 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73   string.** and s
27430 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
27440 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61  me16() returns a
27450 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
27460 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
27470 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
27480 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
27490 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72  meter is the [pr
274a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
274b0 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d  ].** that implem
274c0 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54  ents the [SELECT
274d0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68  ] statement. ^Th
274e0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
274f0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c  er is the.** col
27500 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68  umn number.  ^Th
27510 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
27520 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a  n is number 0..*
27530 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  *.** ^The return
27540 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ed string pointe
27550 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  r is valid until
27560 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65   either the [pre
27570 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27580 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64  .** is destroyed
27590 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
275a0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
275b0 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
275c0 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
275d0 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
275e0 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
275f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
27600 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
27610 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
27620 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63  until the next c
27630 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
27640 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20  3_column_name() 
27650 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
27660 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68  n_name16() on th
27670 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a  e same column..*
27680 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  *.** ^If sqlite3
27690 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20  _malloc() fails 
276a0 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65  during the proce
276b0 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20  ssing of either 
276c0 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20  routine.** (for 
276d0 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61  example during a
276e0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
276f0 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36   UTF-8 to UTF-16
27700 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  ) then a.** NULL
27710 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
27720 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
27730 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c   name of a resul
27740 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
27750 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53  value of the "AS
27760 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20  " clause for.** 
27770 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20  that column, if 
27780 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63  there is an AS c
27790 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65  lause.  If there
277a0 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65   is no AS clause
277b0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d  .** then the nam
277c0 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e of the column 
277d0 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61  is unspecified a
277e0 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72  nd may change fr
277f0 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73  om.** one releas
27800 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74  e of SQLite to t
27810 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73  he next..*/.cons
27820 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
27830 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
27840 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
27850 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
27860 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
27870 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
27880 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
27890 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
278a0 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
278b0 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
278c0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
278d0 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65  nes provide a me
278e0 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ans to determine
278f0 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74   the database, t
27900 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62  able, and.** tab
27910 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69  le column that i
27920 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20  s the origin of 
27930 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73  a particular res
27940 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a  ult column in.**
27950 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
27960 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ent..** ^The nam
27970 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
27980 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f  e or table or co
27990 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75  lumn can be retu
279a0 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65  rned as.** eithe
279b0 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46  r a UTF-8 or UTF
279c0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
279d0 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
279e0 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
279f0 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
27a00 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
27a10 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
27a20 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
27a30 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
27a40 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
27a50 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
27a60 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  e..** ^The retur
27a70 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
27a80 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70  lid until the [p
27a90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27aa0 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a  t] is destroyed.
27ab0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
27ac0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
27ad0 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
27ae0 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
27af0 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
27b00 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
27b10 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
27b20 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
27b30 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
27b40 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  * or until the s
27b50 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
27b60 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20  is requested.** 
27b70 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65  again in a diffe
27b80 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rent encoding..*
27b90 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20  *.** ^The names 
27ba0 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65  returned are the
27bb0 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69   original un-ali
27bc0 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68  ased names of th
27bd0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74  e.** database, t
27be0 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e  able, and column
27bf0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
27c00 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
27c10 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
27c20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
27c30 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54  tatement]..** ^T
27c40 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
27c50 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
27c60 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
27c70 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65  result column re
27c80 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65  turned by.** the
27c90 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72   statement, wher
27ca0 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
27cb0 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
27cc0 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  ent..** ^The lef
27cd0 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  t-most column is
27ce0 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68   column 0 for th
27cf0 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
27d00 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20  .** ^If the Nth 
27d10 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
27d20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
27d30 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
27d40 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79  n or.** subquery
27d50 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
27d60 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
27d70 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
27d80 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a  nctions return.*
27d90 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20  * NULL.  ^These 
27da0 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c  routine might al
27db0 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69  so return NULL i
27dc0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
27dd0 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f  ation error.** o
27de0 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69  ccurs.  ^Otherwi
27df0 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20  se, they return 
27e00 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
27e10 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
27e20 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20  e, table,.** or 
27e30 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72  column that quer
27e40 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  y result column 
27e50 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
27e60 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69  om..**.** ^As wi
27e70 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c  th all other SQL
27e80 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20  ite APIs, those 
27e90 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20  whose names end 
27ea0 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e  with "16" return
27eb0 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  .** UTF-16 encod
27ec0 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74  ed strings and t
27ed0 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f  he other functio
27ee0 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e  ns return UTF-8.
27ef0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50  .**.** ^These AP
27f00 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69  Is are only avai
27f10 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
27f20 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
27f30 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
27f40 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
27f50 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d  UMN_METADATA] C-
27f60 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d  preprocessor sym
27f70 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  bol..**.** If tw
27f80 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
27f90 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
27fa0 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  re of these rout
27fb0 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65  ines against the
27fc0 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65   same.** prepare
27fd0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
27fe0 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61  column at the sa
27ff0 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
28000 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20   results are.** 
28010 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
28020 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
28030 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
28040 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c   or more.** [sql
28050 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
28060 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75  base_name | colu
28070 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
28080 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74  rfaces].** for t
28090 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  he same [prepare
280a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
280b0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a   result column.*
280c0 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  * at the same ti
280d0 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
280e0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
280f0 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  d..*/.const char
28100 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
28110 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73  _database_name(s
28120 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
28130 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
28140 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
28150 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71  tabase_name16(sq
28160 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
28170 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
28180 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
28190 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  le_name(sqlite3_
281a0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
281b0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
281c0 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
281d0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
281e0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
281f0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
28200 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73  mn_origin_name(s
28210 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
28220 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
28230 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
28240 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  igin_name16(sqli
28250 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
28260 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28270 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79   Declared Dataty
28280 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65  pe Of A Query Re
28290 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  sult.**.** ^(The
282a0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
282b0 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
282c0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49  statement]..** I
282d0 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74  f this statement
282e0 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   is a [SELECT] s
282f0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65  tatement and the
28300 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
28310 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72  he.** returned r
28320 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61  esult set of tha
28330 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20  t [SELECT] is a 
28340 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f  table column (no
28350 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  t an.** expressi
28360 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20  on or subquery) 
28370 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65  then the declare
28380 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61  d type of the ta
28390 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73  ble.** column is
283a0 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49   returned.)^  ^I
283b0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
283c0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
283d0 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72  et is an.** expr
283e0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
283f0 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20  ry, then a NULL 
28400 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
28410 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ned..** ^The ret
28420 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
28430 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63  always UTF-8 enc
28440 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f  oded..**.** ^(Fo
28450 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e  r example, given
28460 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
28470 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41  hema:.**.** CREA
28480 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56  TE TABLE t1(c1 V
28490 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61  ARIANT);.**.** a
284a0 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  nd the following
284b0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
284c0 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a   compiled:.**.**
284d0 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20   SELECT c1 + 1, 
284e0 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a  c1 FROM t1;.**.*
284f0 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  * this routine w
28500 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
28510 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22  string "VARIANT"
28520 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20   for the second 
28530 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e  result.** column
28540 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e   (i==1), and a N
28550 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
28560 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74  the first result
28570 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29   column (i==0).)
28580 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
28590 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e  uses dynamic run
285a0 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e  -time typing.  ^
285b0 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  So just because 
285c0 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64  a column.** is d
285d0 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61  eclared to conta
285e0 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
285f0 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65  type does not me
28600 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64  an that the.** d
28610 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68  ata stored in th
28620 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20  at column is of 
28630 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
28640 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  e.  SQLite is.**
28650 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c   strongly typed,
28660 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20   but the typing 
28670 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73  is dynamic not s
28680 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a  tatic.  ^Type.**
28690 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
286a0 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76  ith individual v
286b0 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20  alues, not with 
286c0 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a  the containers.*
286d0 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74  * used to hold t
286e0 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a  hose values..*/.
286f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
28700 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
28710 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
28720 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
28730 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
28740 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71  mn_decltype16(sq
28750 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
28760 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28770 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53  F: Evaluate An S
28780 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  QL Statement.**.
28790 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70  ** After a [prep
287a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
287b0 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65  has been prepare
287c0 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a  d using either.*
287d0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
287e0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
287f0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
28800 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  2()] or one of t
28810 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
28820 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
28830 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b  _prepare()] or [
28840 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
28850 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74  6()], this funct
28860 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63  ion.** must be c
28870 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
28880 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75  e times to evalu
28890 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
288a0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74  t..**.** The det
288b0 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61  ails of the beha
288c0 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69  vior of the sqli
288d0 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72  te3_step() inter
288e0 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f  face depend.** o
288f0 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74  n whether the st
28900 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70  atement was prep
28910 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e  ared using the n
28920 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66  ewer "v2" interf
28930 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ace.** [sqlite3_
28940 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
28950 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
28960 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68  re16_v2()] or th
28970 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a  e older legacy.*
28980 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c  * interface [sql
28990 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
289a0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
289b0 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20  pare16()].  The 
289c0 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65  use of the.** ne
289d0 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  w "v2" interface
289e0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
289f0 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74  for new applicat
28a00 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67  ions but the leg
28a10 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
28a20 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74   will continue t
28a30 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a  o be supported..
28a40 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65  **.** ^In the le
28a50 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
28a60 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
28a70 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
28a80 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a  [SQLITE_BUSY],.*
28a90 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  * [SQLITE_DONE],
28aa0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b   [SQLITE_ROW], [
28ab0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f  SQLITE_ERROR], o
28ac0 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
28ad0 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
28ae0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20  "v2" interface, 
28af0 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72  any of the other
28b00 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20   [result codes] 
28b10 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
28b20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69  result codes] mi
28b30 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
28b40 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  as well..**.** ^
28b50 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
28b60 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
28b70 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
28b80 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
28b90 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
28ba0 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
28bb0 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
28bc0 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d    ^If the statem
28bd0 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54  ent is a [COMMIT
28be0 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f  ].** or occurs o
28bf0 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70  utside of an exp
28c00 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
28c10 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20  n, then you can 
28c20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61  retry the.** sta
28c30 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20  tement.  If the 
28c40 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
28c50 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20   a [COMMIT] and 
28c60 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e  occurs within an
28c70 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61  .** explicit tra
28c80 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f  nsaction then yo
28c90 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63  u should rollbac
28ca0 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
28cb0 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74  n before.** cont
28cc0 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  inuing..**.** ^[
28cd0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61  SQLITE_DONE] mea
28ce0 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74  ns that the stat
28cf0 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68  ement has finish
28d00 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20  ed executing.** 
28d10 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73  successfully.  s
28d20 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
28d30 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
28d40 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73  ed again on this
28d50 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
28d60 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73  ine without firs
28d70 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
28d80 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72  e3_reset()] to r
28d90 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c  eset the virtual
28da0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b  .** machine back
28db0 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
28dc0 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  state..**.** ^If
28dd0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
28de0 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
28df0 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
28e00 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  ta, then [SQLITE
28e10 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75  _ROW].** is retu
28e20 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61  rned each time a
28e30 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61   new row of data
28e40 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72   is ready for pr
28e50 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a  ocessing by the.
28e60 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76  ** caller. The v
28e70 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63  alues may be acc
28e80 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20  essed using the 
28e90 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
28ea0 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71  unctions]..** sq
28eb0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20  lite3_step() is 
28ec0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20  called again to 
28ed0 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78  retrieve the nex
28ee0 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a  t row of data..*
28ef0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52  *.** ^[SQLITE_ER
28f00 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ROR] means that 
28f10 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
28f20 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73   (such as a cons
28f30 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74  traint.** violat
28f40 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65  ion) has occurre
28f50 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  d.  sqlite3_step
28f60 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
28f70 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
28f80 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65  .** the VM. More
28f90 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79   information may
28fa0 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c   be found by cal
28fb0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72  ling [sqlite3_er
28fc0 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74  rmsg()]..** ^Wit
28fd0 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  h the legacy int
28fe0 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73  erface, a more s
28ff0 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
29000 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c  de (for example,
29010 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
29020 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  RRUPT], [SQLITE_
29030 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45  SCHEMA], [SQLITE
29040 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73  _CORRUPT], and s
29050 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20  o forth).** can 
29060 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63  be obtained by c
29070 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
29080 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a  reset()] on the.
29090 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
290a0 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68  tement].  ^In th
290b0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
290c0 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70  ,.** the more sp
290d0 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
290e0 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69  e is returned di
290f0 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65  rectly by sqlite
29100 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_step()..**.** 
29110 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
29120 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74  means that the t
29130 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20  his routine was 
29140 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72  called inappropr
29150 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61  iately..** Perha
29160 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64  ps it was called
29170 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
29180 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
29190 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62  has.** already b
291a0 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  een [sqlite3_fin
291b0 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
291c0 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61  d] or on one tha
291d0 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75  t had.** previou
291e0 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51  sly returned [SQ
291f0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b  LITE_ERROR] or [
29200 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f  SQLITE_DONE].  O
29210 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65  r it could.** be
29220 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
29230 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
29240 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62   connection is b
29250 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f  eing used by two
29260 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65   or.** more thre
29270 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
29280 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a  moment in time..
29290 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65  **.** For all ve
292a0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
292b0 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75   up to and inclu
292c0 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61  ding 3.6.23.1, a
292d0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
292e0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61  ite3_reset()] wa
292f0 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72  s required after
29300 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
29310 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e  returned anythin
29320 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20  g.** other than 
29330 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66  [SQLITE_ROW] bef
29340 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65  ore any subseque
29350 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  nt invocation of
29360 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
29370 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20  ().  Failure to 
29380 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
29390 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  ed statement usi
293a0 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
293b0 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72  reset()] would r
293c0 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c  esult in an [SQL
293d0 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75  ITE_MISUSE] retu
293e0 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74  rn from.** sqlit
293f0 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20  e3_step().  But 
29400 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e  after version 3.
29410 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f  6.23.1, sqlite3_
29420 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20  step() began.** 
29430 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
29440 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61  _reset()] automa
29450 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20  tically in this 
29460 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74  circumstance rat
29470 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75  her.** than retu
29480 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49  rning [SQLITE_MI
29490 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20  SUSE].  This is 
294a0 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61  not considered a
294b0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a   compatibility.*
294c0 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20  * break because 
294d0 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  any application 
294e0 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76  that ever receiv
294f0 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53  es an SQLITE_MIS
29500 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20  USE error.** is 
29510 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69  broken by defini
29520 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49  tion.  The [SQLI
29530 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45  TE_OMIT_AUTORESE
29540 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
29550 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65  option.** can be
29560 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65   used to restore
29570 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61   the legacy beha
29580 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47  vior..**.** <b>G
29590 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41  oofy Interface A
295a0 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65  lert:</b> In the
295b0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
295c0 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  e, the sqlite3_s
295d0 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77  tep().** API alw
295e0 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65  ays returns a ge
295f0 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65  neric error code
29600 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
29610 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a  , following any.
29620 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74  ** error other t
29630 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  han [SQLITE_BUSY
29640 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49  ] and [SQLITE_MI
29650 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74  SUSE].  You must
29660 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
29670 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
29680 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
29690 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  )] in order to f
296a0 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  ind one of the.*
296b0 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  * specific [erro
296c0 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65  r codes] that be
296d0 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74  tter describes t
296e0 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20  he error..** We 
296f0 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20  admit that this 
29700 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67  is a goofy desig
29710 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20  n.  The problem 
29720 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a  has been fixed.*
29730 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20  * with the "v2" 
29740 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79  interface.  If y
29750 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f  ou prepare all o
29760 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65  f your SQL state
29770 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65  ments.** using e
29780 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
29790 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
297a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
297b0 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64  16_v2()] instead
297c0 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63  .** of the legac
297d0 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
297e0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
297f0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
29800 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74  interfaces,.** t
29810 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65  hen the more spe
29820 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
29830 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
29840 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
29850 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
29860 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
29870 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
29880 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  s recommended..*
29890 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
298a0 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
298b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
298c0 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
298d0 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
298e0 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  t set.**.** ^The
298f0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
29900 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65  unt(P) interface
29910 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
29920 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
29930 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
29940 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
29950 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61  lt set of [prepa
29960 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
29970 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65  ..** ^If prepare
29980 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f  d statement P do
29990 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75  es not have resu
299a0 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74  lts ready to ret
299b0 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c  urn.** (via call
299c0 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
299d0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73  3_column_int | s
299e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28  qlite3_column_*(
299f0 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  )] of.** interfa
29a00 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65  ces) then sqlite
29a10 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
29a20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54  returns 0..** ^T
29a30 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
29a40 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
29a50 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20   also returns 0 
29a60 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70  if P is a NULL p
29a70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  ointer..** ^The 
29a80 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
29a90 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65  nt(P) routine re
29aa0 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70  turns 0 if the p
29ab0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a  revious call to.
29ac0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
29ad0 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53  ](P) returned [S
29ae0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54  QLITE_DONE].  ^T
29af0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
29b00 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c  count(P).** will
29b10 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f   return non-zero
29b20 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c   if previous cal
29b30 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
29b40 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a  ep](P) returned.
29b50 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ** [SQLITE_ROW],
29b60 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63   except in the c
29b70 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47  ase of the [PRAG
29b80 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76  MA incremental_v
29b90 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20  acuum].** where 
29ba0 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
29bb0 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63  s zero since eac
29bc0 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d  h step of that m
29bd0 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61  ulti-step.** pra
29be0 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f  gma returns 0 co
29bf0 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a  lumns of data..*
29c00 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
29c10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
29c20 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73  ount()].*/.int s
29c30 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
29c40 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
29c50 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
29c60 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65  API3REF: Fundame
29c70 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a  ntal Datatypes.*
29c80 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
29c90 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28  TE_TEXT.**.** ^(
29ca0 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53  Every value in S
29cb0 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66  QLite has one of
29cc0 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61   five fundamenta
29cd0 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a  l datatypes:.**.
29ce0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
29cf0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
29d00 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34  teger.** <li> 64
29d10 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69  -bit IEEE floati
29d20 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a  ng point number.
29d30 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a  ** <li> string.*
29d40 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c  * <li> BLOB.** <
29d50 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c  li> NULL.** </ul
29d60 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  >)^.**.** These 
29d70 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f  constants are co
29d80 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  des for each of 
29d90 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a  those types..**.
29da0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
29db0 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e   SQLITE_TEXT con
29dc0 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75  stant was also u
29dd0 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  sed in SQLite ve
29de0 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61  rsion 2.** for a
29df0 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66   completely diff
29e00 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20  erent meaning.  
29e10 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69  Software that li
29e20 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68  nks against both
29e30 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
29e40 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20  on 2 and SQLite 
29e50 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64  version 3 should
29e60 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58   use SQLITE3_TEX
29e70 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45  T, not.** SQLITE
29e80 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e  _TEXT..*/.#defin
29e90 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52  e SQLITE_INTEGER
29ea0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
29eb0 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64  TE_FLOAT    2.#d
29ec0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f  efine SQLITE_BLO
29ed0 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  B     4.#define 
29ee0 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20  SQLITE_NULL     
29ef0 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  5.#ifdef SQLITE_
29f00 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c  TEXT.# undef SQL
29f10 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23  ITE_TEXT.#else.#
29f20 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
29f30 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66  EXT     3.#endif
29f40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33  .#define SQLITE3
29f50 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a  _TEXT     3../*.
29f60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
29f70 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20  ult Values From 
29f80 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f  A Query.** KEYWO
29f90 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63  RDS: {column acc
29fa0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  ess functions}.*
29fb0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
29fc0 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65  nes form the "re
29fd0 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66  sult set" interf
29fe0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ace..**.** ^Thes
29ff0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
2a000 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
2a010 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c  out a single col
2a020 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  umn of the curre
2a030 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77  nt.** result row
2a040 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49   of a query.  ^I
2a050 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65  n every case the
2a060 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2a070 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  is a pointer.** 
2a080 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
2a090 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2a0a0 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61   is being evalua
2a0b0 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ted (the [sqlite
2a0c0 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74  3_stmt*].** that
2a0d0 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72   was returned fr
2a0e0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  om [sqlite3_prep
2a0f0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  are_v2()] or one
2a100 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73   of its variants
2a110 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63  ).** and the sec
2a120 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
2a130 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
2a140 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63   column for whic
2a150 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
2a160 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
2a170 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ned. ^The leftmo
2a180 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  st column of the
2a190 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20   result set has 
2a1a0 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20  the index 0..** 
2a1b0 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63  ^The number of c
2a1c0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
2a1d0 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65  sult can be dete
2a1e0 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20  rmined using.** 
2a1f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2a200 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  count()]..**.** 
2a210 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
2a220 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75  ment does not cu
2a230 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f  rrently point to
2a240 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72   a valid row, or
2a250 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   if the.** colum
2a260 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  n index is out o
2a270 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73  f range, the res
2a280 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
2a290 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
2a2a0 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
2a2b0 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
2a2c0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2a2d0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2a2e0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
2a2f0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
2a300 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
2a310 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2a320 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
2a330 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65  finalize()] have
2a340 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62   been called sub
2a350 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66  sequently..** If
2a360 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
2a370 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
2a380 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
2a390 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
2a3a0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2a3b0 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73  e()] or after [s
2a3c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
2a3d0 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73  as returned.** s
2a3e0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
2a3f0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
2a400 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
2a410 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
2a420 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  If [sqlite3_step
2a430 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2a440 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
2a450 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2a460 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66  .** are called f
2a470 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20  rom a different 
2a480 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79  thread while any
2a490 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2a4a0 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e  es.** are pendin
2a4b0 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  g, then the resu
2a4c0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2a4d0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
2a4e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2a4f0 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
2a500 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  rns the.** [SQLI
2a510 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
2a520 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20  atype code] for 
2a530 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61  the initial data
2a540 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20   type.** of the 
2a550 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20  result column.  
2a560 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61  ^The returned va
2a570 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  lue is one of [S
2a580 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a  QLITE_INTEGER],.
2a590 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ** [SQLITE_FLOAT
2a5a0 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d  ], [SQLITE_TEXT]
2a5b0 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c  , [SQLITE_BLOB],
2a5c0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   or [SQLITE_NULL
2a5d0 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a  ].  The value.**
2a5e0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2a5f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2a600 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69  () is only meani
2a610 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65  ngful if no type
2a620 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  .** conversions 
2a630 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73  have occurred as
2a640 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77   described below
2a650 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20  .  After a type 
2a660 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74  conversion,.** t
2a670 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
2a680 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2a690 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e  umn_type() is un
2a6a0 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65  defined.  Future
2a6b0 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
2a6c0 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67  SQLite may chang
2a6d0 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  e the behavior o
2a6e0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  f sqlite3_column
2a6f0 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f  _type().** follo
2a700 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76  wing a type conv
2a710 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ersion..**.** ^I
2a720 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2a730 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20  a BLOB or UTF-8 
2a740 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
2a750 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2a760 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ytes().** routin
2a770 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2a780 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2a790 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
2a7a0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2a7b0 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
2a7c0 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
2a7d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a7e0 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
2a7f0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
2a800 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
2a810 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2a820 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
2a830 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2a840 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
2a850 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
2a860 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75  column_bytes() u
2a870 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
2a880 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
2a890 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
2a8a0 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72  e to a UTF-8 str
2a8b0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
2a8c0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2a8d0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
2a8e0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2a8f0 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
2a900 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2a910 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65  olumn_bytes() re
2a920 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
2a930 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2a940 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
2a950 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e  F-16 string then
2a960 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
2a970 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a  umn_bytes16().**
2a980 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2a990 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2a9a0 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
2a9b0 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
2a9c0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2a9d0 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
2a9e0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2a9f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2aa00 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
2aa10 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36  string to UTF-16
2aa20 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
2aa30 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2aa40 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
2aa50 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
2aa60 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
2aa70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2aa80 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a  bytes16() uses.*
2aa90 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
2aaa0 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
2aab0 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
2aac0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
2aad0 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
2aae0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2aaf0 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
2ab00 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2ab10 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
2ab20 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2ab30 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75  n_bytes16() retu
2ab40 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
2ab50 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
2ab60 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
2ab70 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
2ab80 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
2ab90 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2aba0 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75  ()] do not inclu
2abb0 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  de the zero term
2abc0 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65  inators at the e
2abd0 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
2abe0 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69  ing.  ^For clari
2abf0 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72  ty: the values r
2ac00 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
2ac10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2ac20 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tes()] and [sqli
2ac30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2ac40 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75  16()] are the nu
2ac50 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
2ac60 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20   in the string, 
2ac70 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
2ac80 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
2ac90 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74  .** ^Strings ret
2aca0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2acb0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
2acc0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2acd0 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
2ace0 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67  ven empty string
2acf0 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65  s, are always ze
2ad00 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
2ad10 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76  ^The return.** v
2ad20 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
2ad30 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
2ad40 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74  for a zero-lengt
2ad50 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c  h BLOB is a NULL
2ad60 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
2ad70 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75  ^The object retu
2ad80 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
2ad90 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
2ada0 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f   is an.** [unpro
2adb0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2adc0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41  alue] object.  A
2add0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
2ade0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2adf0 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ct.** may only b
2ae00 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c  e used with [sql
2ae10 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
2ae20 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2ae30 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e  result_value()].
2ae40 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72  .** If the [unpr
2ae50 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2ae60 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65  value] object re
2ae70 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
2ae80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2ae90 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  ue()] is used in
2aea0 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20   any other way, 
2aeb0 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a  including calls.
2aec0 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  ** to routines l
2aed0 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  ike [sqlite3_val
2aee0 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69  ue_int()], [sqli
2aef0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
2af00 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
2af10 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
2af20 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
2af30 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
2af40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
2af50 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74  utines attempt t
2af60 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
2af70 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70  lue where approp
2af80 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20  riate.  ^For.** 
2af90 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20  example, if the 
2afa0 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
2afb0 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54  ntation is FLOAT
2afc0 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75   and a text resu
2afd0 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74  lt.** is request
2afe0 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  ed, [sqlite3_snp
2aff0 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64  rintf()] is used
2b000 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70   internally to p
2b010 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f  erform the.** co
2b020 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74  nversion automat
2b030 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66  ically.  ^(The f
2b040 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64  ollowing table d
2b050 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65  etails the conve
2b060 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61  rsions.** that a
2b070 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a  re applied:.**.*
2b080 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  * <blockquote>.*
2b090 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
2b0a0 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
2b0b0 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70   Internal<br>Typ
2b0c0 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64  e <th> Requested
2b0d0 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43  <br>Type <th>  C
2b0e0 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onversion.**.** 
2b0f0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2b100 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2b110 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2b120 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
2b130 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  ULL    <td>  FLO
2b140 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  AT    <td> Resul
2b150 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e  t is 0.0.** <tr>
2b160 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
2b170 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2b180 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  > Result is NULL
2b190 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
2b1a0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
2b1b0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2b1c0 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  > Result is NULL
2b1d0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
2b1e0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
2b1f0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2b200 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69  > Convert from i
2b210 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a  nteger to float.
2b220 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
2b230 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54  GER  <td>   TEXT
2b240 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
2b250 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
2b260 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
2b270 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
2b280 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
2b290 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52   Same as INTEGER
2b2a0 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
2b2b0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
2b2c0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2b2d0 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f  Convert from flo
2b2e0 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a  at to integer.**
2b2f0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
2b300 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
2b310 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
2b320 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
2b330 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
2b340 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
2b350 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
2b360 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54  e as FLOAT->TEXT
2b370 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
2b380 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  XT    <td> INTEG
2b390 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  ER   <td> Use at
2b3a0 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
2b3b0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
2b3c0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73  FLOAT    <td> Us
2b3d0 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e  e atof().** <tr>
2b3e0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2b3f0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2b400 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c  > No change.** <
2b410 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2b420 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2b430 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20  <td> Convert to 
2b440 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74  TEXT then use at
2b450 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
2b460 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
2b470 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
2b480 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
2b490 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a  en use atof().**
2b4a0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
2b4b0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
2b4c0 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72    <td> Add a zer
2b4d0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20  o terminator if 
2b4e0 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c  needed.** </tabl
2b4f0 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
2b500 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te>)^.**.** The 
2b510 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65  table above make
2b520 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73  s reference to s
2b530 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
2b540 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69  y functions atoi
2b550 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29  ().** and atof()
2b560 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e  .  SQLite does n
2b570 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68  ot really use th
2b580 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
2b590 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77  It has its.** ow
2b5a0 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74  n equivalent int
2b5b0 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20  ernal routines. 
2b5c0 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20   The atoi() and 
2b5d0 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65  atof() names are
2b5e0 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20  .** used in the 
2b5f0 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74  table for brevit
2b600 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68  y and because th
2b610 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20  ey are familiar 
2b620 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f  to most.** C pro
2b630 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  grammers..**.** 
2b640 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74  Note that when t
2b650 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
2b660 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20  occur, pointers 
2b670 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f  returned by prio
2b680 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  r.** calls to sq
2b690 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2b6a0 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  b(), sqlite3_col
2b6b0 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f  umn_text(), and/
2b6c0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
2b6d0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61  lumn_text16() ma
2b6e0 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  y be invalidated
2b6f0 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72  ..** Type conver
2b700 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65  sions and pointe
2b710 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20  r invalidations 
2b720 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69  might occur.** i
2b730 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
2b740 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  cases:.**.** <ul
2b750 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
2b760 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
2b770 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69   a BLOB and sqli
2b780 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2b790 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
2b7a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2b7b0 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
2b7c0 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   A zero-terminat
2b7d0 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20  or might.**     
2b7e0 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65   need to be adde
2b7f0 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e  d to the string.
2b800 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
2b810 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2b820 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20  t is UTF-8 text 
2b830 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2b840 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a  mn_bytes16() or.
2b850 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
2b860 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
2b870 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
2b880 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
2b890 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
2b8a0 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69    to UTF-16.</li
2b8b0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
2b8c0 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
2b8d0 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64   UTF-16 text and
2b8e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b8f0 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20  bytes() or.**   
2b900 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
2b910 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c  n_text() is call
2b920 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
2b930 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
2b940 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
2b950 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  F-8.</li>.** </u
2b960 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72  l>.**.** ^Conver
2b970 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54  sions between UT
2b980 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31  F-16be and UTF-1
2b990 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64  6le are always d
2b9a0 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64  one in place and
2b9b0 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c   do.** not inval
2b9c0 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f  idate a prior po
2b9d0 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66  inter, though of
2b9e0 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74   course the cont
2b9f0 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65  ent of the buffe
2ba00 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72  r.** that the pr
2ba10 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65  ior pointer refe
2ba20 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65  rences will have
2ba30 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20   been modified. 
2ba40 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20   Other kinds.** 
2ba50 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72  of conversion ar
2ba60 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  e done in place 
2ba70 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69  when it is possi
2ba80 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d  ble, but sometim
2ba90 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e  es they.** are n
2baa0 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
2bab0 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
2bac0 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
2bad0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
2bae0 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20  *.** The safest 
2baf0 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72  and easiest to r
2bb00 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69  emember policy i
2bb10 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73  s to invoke thes
2bb20 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e  e routines.** in
2bb30 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
2bb40 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a  owing ways:.**.*
2bb50 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  * <ul>.**  <li>s
2bb60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2bb70 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
2bb80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bb90 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
2bba0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
2bbb0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
2bbc0 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
2bbd0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
2bbe0 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
2bbf0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2bc00 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
2bc10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2bc20 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
2bc30 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f  </ul>.**.** In o
2bc40 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20  ther words, you 
2bc50 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69  should call sqli
2bc60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2bc70 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  ),.** sqlite3_co
2bc80 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20  lumn_blob(), or 
2bc90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2bca0 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f  ext16() first to
2bcb0 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c   force the resul
2bcc0 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65  t.** into the de
2bcd0 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68  sired format, th
2bce0 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  en invoke sqlite
2bcf0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2bd00 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
2bd10 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2bd20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65  to find the size
2bd30 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20   of the result. 
2bd40 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   Do not mix call
2bd50 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  s.** to sqlite3_
2bd60 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
2bd70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bd80 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c  blob() with call
2bd90 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
2bda0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2bdb0 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78  , and do not mix
2bdc0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2bdd0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2bde0 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20  ).** with calls 
2bdf0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
2be00 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a  n_bytes()..**.**
2be10 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72   ^The pointers r
2be20 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69  eturned are vali
2be30 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63  d until a type c
2be40 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
2be50 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64   as.** described
2be60 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c   above, or until
2be70 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2be80 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
2be90 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
2bea0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2beb0 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54  ] is called.  ^T
2bec0 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20  he memory space 
2bed0 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72  used to hold str
2bee0 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42  ings.** and BLOB
2bef0 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d  s is freed autom
2bf00 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62  atically.  Do <b
2bf10 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68  >not</b> pass th
2bf20 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
2bf30 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ned.** [sqlite3_
2bf40 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
2bf50 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2bf60 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
2bf70 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
2bf80 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ree()]..**.** ^(
2bf90 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
2bfa0 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
2bfb0 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65  urs during the e
2bfc0 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79  valuation of any
2bfd0 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75  .** of these rou
2bfe0 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74  tines, a default
2bff0 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
2c000 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
2c010 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74   value.** is eit
2c020 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20  her the integer 
2c030 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  0, the floating 
2c040 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30  point number 0.0
2c050 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  , or a NULL.** p
2c060 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75  ointer.  Subsequ
2c070 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
2c080 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
2c090 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
2c0a0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29  [SQLITE_NOMEM].)
2c0b0 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ^.*/.const void 
2c0c0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2c0d0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
2c0e0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
2c0f0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2c100 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  n_bytes(sqlite3_
2c110 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2c120 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2c130 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c  lumn_bytes16(sql
2c140 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2c150 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71  iCol);.double sq
2c160 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
2c170 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
2c180 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
2c190 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2c1a0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
2c1b0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
2c1c0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
2c1d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
2c1e0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2c1f0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
2c200 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
2c210 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2c220 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
2c230 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
2c240 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2c250 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2c260 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2c270 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
2c280 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2c290 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
2c2a0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
2c2b0 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
2c2c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2c2d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2c2e0 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
2c2f0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
2c300 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
2c310 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
2c320 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2c330 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75  e3_finalize() fu
2c340 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
2c350 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72   to delete a [pr
2c360 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c370 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  ]..** ^If the mo
2c380 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
2c390 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
2c3a0 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65  ement encountere
2c3b0 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f  d no errors.** o
2c3c0 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  r if the stateme
2c3d0 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e  nt is never been
2c3e0 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e   evaluated, then
2c3f0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2c400 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53  e() returns.** S
2c410 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74  QLITE_OK.  ^If t
2c420 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
2c430 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61  valuation of sta
2c440 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c  tement S failed,
2c450 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
2c460 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74  _finalize(S) ret
2c470 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72  urns the appropr
2c480 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
2c490 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
2c4a0 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a  d error code]..*
2c4b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2c4c0 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f  3_finalize(S) ro
2c4d0 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c  utine can be cal
2c4e0 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  led at any point
2c4f0 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c   during.** the l
2c500 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72  ife cycle of [pr
2c510 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c520 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73  ] S:.** before s
2c530 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76  tatement S is ev
2c540 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66  er evaluated, af
2c550 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f  ter.** one or mo
2c560 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  re calls to [sql
2c570 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f  ite3_reset()], o
2c580 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c  r after any call
2c590 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
2c5a0 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65  step()] regardle
2c5b0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
2c5c0 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65   not the stateme
2c5d0 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65  nt has.** comple
2c5e0 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a  ted execution..*
2c5f0 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73  *.** ^Invoking s
2c600 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2c610 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) on a NULL poin
2c620 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ter is a harmles
2c630 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54  s no-op..**.** T
2c640 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
2c650 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65  ust finalize eve
2c660 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ry [prepared sta
2c670 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72  tement] in order
2c680 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73   to avoid.** res
2c690 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74  ource leaks.  It
2c6a0 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65   is a grievous e
2c6b0 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  rror for the app
2c6c0 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20  lication to try 
2c6d0 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70  to use.** a prep
2c6e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
2c6f0 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
2c700 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79   finalized.  Any
2c710 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72   use of a prepar
2c720 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
2c730 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
2c740 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20  n finalized can 
2c750 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
2c760 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73  ned and.** undes
2c770 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20  irable behavior 
2c780 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74  such as segfault
2c790 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75  s and heap corru
2c7a0 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ption..*/.int sq
2c7b0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73  lite3_finalize(s
2c7c0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2c7d0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2c7e0 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72  3REF: Reset A Pr
2c7f0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2c800 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
2c810 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  e sqlite3_reset(
2c820 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
2c830 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20  lled to reset a 
2c840 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c850 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62  ent].** object b
2c860 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
2c870 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20  al state, ready 
2c880 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65  to be re-execute
2c890 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73  d..** ^Any SQL s
2c8a0 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c  tatement variabl
2c8b0 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75  es that had valu
2c8c0 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d  es bound to them
2c8d0 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73   using.** the [s
2c8e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2c8f0 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
2c900 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20  *() API] retain 
2c910 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a  their values..**
2c920 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c   Use [sqlite3_cl
2c930 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20  ear_bindings()] 
2c940 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e  to reset the bin
2c950 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dings..**.** ^Th
2c960 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
2c970 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
2c980 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61  esets the [prepa
2c990 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2c9a0 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20  .** back to the 
2c9b0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73  beginning of its
2c9c0 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20   program..**.** 
2c9d0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
2c9e0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
2c9f0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
2ca00 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
2ca10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2ca20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2ca30 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _ROW] or [SQLITE
2ca40 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66  _DONE],.** or if
2ca50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2ca60 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66  )] has never bef
2ca70 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ore been called 
2ca80 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73  on S,.** then [s
2ca90 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2caa0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
2cab0 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  _OK]..**.** ^If 
2cac0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2cad0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2cae0 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
2caf0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2cb00 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69  tatement] S indi
2cb10 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20  cated an error, 
2cb20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  then.** [sqlite3
2cb30 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
2cb40 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  ns an appropriat
2cb50 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  e [error code]..
2cb60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
2cb70 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
2cb80 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74  terface does not
2cb90 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
2cba0 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71  es.** of any [sq
2cbb0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2cbc0 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65  bindings] on the
2cbd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2cbe0 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20  ment] S..*/.int 
2cbf0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
2cc00 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2cc10 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2cc20 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
2cc30 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
2cc40 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
2cc50 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
2cc60 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a  ation routines}.
2cc70 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
2cc80 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2cc90 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a  d SQL function}.
2cca0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
2ccb0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2ccc0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d  d SQL functions}
2ccd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  .**.** ^These fu
2cce0 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74  nctions (collect
2ccf0 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22  ively known as "
2cd00 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
2cd10 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20  n routines").** 
2cd20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
2cd30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
2cd40 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74   aggregates or t
2cd50 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62  o redefine the b
2cd60 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78  ehavior.** of ex
2cd70 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74  isting SQL funct
2cd80 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
2cd90 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69  es.  The only di
2cda0 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65  fferences betwee
2cdb0 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69  n.** these routi
2cdc0 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74  nes are the text
2cdd0 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74   encoding expect
2cde0 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65  ed for.** the se
2cdf0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28  cond parameter (
2ce00 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2ce10 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63  function being c
2ce20 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74  reated).** and t
2ce30 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61  he presence or a
2ce40 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74  bsence of a dest
2ce50 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
2ce60 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  for.** the appli
2ce70 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
2ce80 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
2ce90 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2cea0 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
2ceb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
2cec0 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
2ced0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
2cee0 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61  be added.  ^If a
2cef0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
2cf00 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
2cf10 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
2cf20 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70  nection then app
2cf30 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2cf40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d   SQL functions m
2cf50 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20  ust be added.** 
2cf60 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
2cf70 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61   connection sepa
2cf80 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  rately..**.** ^T
2cf90 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2cfa0 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
2cfb0 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
2cfc0 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65  ion to be create
2cfd0 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65  d or.** redefine
2cfe0 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20  d.  ^The length 
2cff0 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
2d000 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
2d010 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a  tes in a UTF-8.*
2d020 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  * representation
2d030 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74  , exclusive of t
2d040 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
2d050 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  or.  ^Note that 
2d060 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67  the name.** leng
2d070 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55  th limit is in U
2d080 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20  TF-8 bytes, not 
2d090 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55  characters nor U
2d0a0 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a  TF-16 bytes.  .*
2d0b0 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74  * ^Any attempt t
2d0c0 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74  o create a funct
2d0d0 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65  ion with a longe
2d0e0 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72  r name.** will r
2d0f0 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45  esult in [SQLITE
2d100 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72  _MISUSE] being r
2d110 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
2d120 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
2d130 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73  ter (nArg).** is
2d140 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
2d150 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
2d160 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
2d170 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
2d180 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70  akes. ^If this p
2d190 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20  arameter is -1, 
2d1a0 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
2d1b0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
2d1c0 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
2d1d0 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
2d1e0 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30  uments between 0
2d1f0 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a   and the limit.*
2d200 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65  * set by [sqlite
2d210 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
2d220 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
2d230 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74  ARG]).  If the t
2d240 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
2d250 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d  r is less than -
2d260 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
2d270 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62  n 127 then the b
2d280 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
2d290 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
2d2a0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
2d2b0 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20  eter, eTextRep, 
2d2c0 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a  specifies what.*
2d2d0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
2d2e0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
2d2f0 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f  this SQL functio
2d300 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a  n prefers for.**
2d310 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e   its parameters.
2d320 20 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63    Every SQL func
2d330 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
2d340 69 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65  ion must be able
2d350 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68   to work.** with
2d360 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65   UTF-8, UTF-16le
2d370 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20  , or UTF-16be.  
2d380 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65  But some impleme
2d390 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a  ntations may be.
2d3a0 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e  ** more efficien
2d3b0 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64  t with one encod
2d3c0 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72  ing than another
2d3d0 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  .  ^An applicati
2d3e0 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65  on may.** invoke
2d3f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2d400 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71  function() or sq
2d410 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2d420 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70  ction16() multip
2d430 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68  le.** times with
2d440 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2d450 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66  on but with diff
2d460 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20  erent values of 
2d470 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68  eTextRep..** ^Wh
2d480 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
2d490 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
2d4a0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
2d4b0 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
2d4c0 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
2d4d0 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
2d4e0 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
2d4f0 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
2d500 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
2d510 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e  * If there is on
2d520 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c  ly a single impl
2d530 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68  ementation which
2d540 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77   does not care w
2d550 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f  hat text.** enco
2d560 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ding is used, th
2d570 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  en the fourth ar
2d580 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
2d590 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a   [SQLITE_ANY]..*
2d5a0 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68  *.** ^(The fifth
2d5b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
2d5c0 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
2d5d0 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
2d5e0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ntation of the.*
2d5f0 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  * function can g
2d600 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
2d610 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
2d620 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
2d630 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ata()].)^.**.** 
2d640 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65  ^The sixth, seve
2d650 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70  nth and eighth p
2d660 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63  arameters, xFunc
2d670 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  , xStep and xFin
2d680 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74  al, are.** point
2d690 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67  ers to C-languag
2d6a0 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  e functions that
2d6b0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
2d6c0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
2d6d0 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20  * aggregate. ^A 
2d6e0 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
2d6f0 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
2d700 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2d710 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63  f the xFunc.** c
2d720 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55  allback only; NU
2d730 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74  LL pointers must
2d740 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
2d750 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  e xStep and xFin
2d760 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  al.** parameters
2d770 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20  . ^An aggregate 
2d780 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
2d790 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
2d7a0 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70  ntation of xStep
2d7b0 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  .** and xFinal a
2d7c0 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  nd NULL pointer 
2d7d0 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66  must be passed f
2d7e0 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65  or xFunc. ^To de
2d7f0 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67  lete an existing
2d800 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
2d810 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70   or aggregate, p
2d820 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ass NULL pointer
2d830 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20  s for all three 
2d840 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  function.** call
2d850 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  backs..**.** ^(I
2d860 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61  f the ninth para
2d870 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2d880 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2d890 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  _v2() is not NUL
2d8a0 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  L,.** then it is
2d8b0 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
2d8c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2d8d0 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a  data pointer. .*
2d8e0 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72  * The destructor
2d8f0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
2d900 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
2d910 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72   deleted, either
2d920 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65   by being.** ove
2d930 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20  rloaded or when 
2d940 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2d950 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29  nection closes.)
2d960 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75  ^.** ^The destru
2d970 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76  ctor is also inv
2d980 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c  oked if the call
2d990 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
2d9a0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
2d9b0 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57  2() fails..** ^W
2d9c0 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74  hen the destruct
2d9d0 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  or callback of t
2d9e0 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74  he tenth paramet
2d9f0 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69  er is invoked, i
2da00 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61  t.** is passed a
2da10 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
2da20 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79   which is a copy
2da30 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
2da40 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69  ion data .** poi
2da50 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74  nter which was t
2da60 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
2da70 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
2da80 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
2da90 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ()..**.** ^It is
2daa0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65   permitted to re
2dab0 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20  gister multiple 
2dac0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2dad0 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66  of the same.** f
2dae0 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68  unctions with th
2daf0 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20  e same name but 
2db00 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66  with either diff
2db10 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66  ering numbers of
2db20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  .** arguments or
2db30 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65   differing prefe
2db40 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
2db50 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69  ngs.  ^SQLite wi
2db60 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d  ll use.** the im
2db70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61  plementation tha
2db80 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d  t most closely m
2db90 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69  atches the way i
2dba0 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53  n which the.** S
2dbb0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  QL function is u
2dbc0 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  sed.  ^A functio
2dbd0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2dbe0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61   with a non-nega
2dbf0 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72  tive.** nArg par
2dc00 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74  ameter is a bett
2dc10 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
2dc20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2dc30 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20  ntation with.** 
2dc40 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e  a negative nArg.
2dc50 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68    ^A function wh
2dc60 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  ere the preferre
2dc70 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a  d text encoding.
2dc80 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64  ** matches the d
2dc90 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67  atabase encoding
2dca0 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20   is a better.** 
2dcb0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
2dcc0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
2dcd0 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
2dce0 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66  erent.  .** ^A f
2dcf0 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
2dd00 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
2dd10 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e  rence is between
2dd20 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46   UTF16le and UTF
2dd30 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f  16be.** is a clo
2dd40 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ser match than a
2dd50 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
2dd60 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
2dd70 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65  ference is.** be
2dd80 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55  tween UTF8 and U
2dd90 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69  TF16..**.** ^Bui
2dda0 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20  lt-in functions 
2ddb0 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65  may be overloade
2ddc0 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61  d by new applica
2ddd0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2dde0 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  ctions..**.** ^A
2ddf0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
2de00 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
2de10 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63  s permitted to c
2de20 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  all other.** SQL
2de30 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20  ite interfaces. 
2de40 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63   However, such c
2de50 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a  alls must not.**
2de60 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
2de70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e  ase connection n
2de80 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72  or finalize or r
2de90 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
2dea0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
2deb0 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63  n which the func
2dec0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
2ded0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2dee0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2def0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
2df00 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
2df10 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
2df20 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
2df30 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
2df40 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
2df50 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
2df60 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2df70 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2df80 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
2df90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2dfa0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2dfb0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
2dfc0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
2dfd0 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73  ntext*).);.int s
2dfe0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2dff0 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  nction16(.  sqli
2e000 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
2e010 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e   void *zFunction
2e020 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
2e030 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
2e040 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
2e050 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
2e060 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2e070 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2e080 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2e090 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
2e0a0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2e0b0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2e0c0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
2e0d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2e0e0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2e0f0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
2e100 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
2e110 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
2e120 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
2e130 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
2e140 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
2e150 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
2e160 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
2e170 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2e180 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2e190 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
2e1a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2e1b0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2e1c0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2e1d0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
2e1e0 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f  _context*),.  vo
2e1f0 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
2e200 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
2e210 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e  API3REF: Text En
2e220 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68  codings.**.** Th
2e230 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66  ese constant def
2e240 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
2e250 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74  s that represent
2e260 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20   the various.** 
2e270 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73  text encodings s
2e280 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
2e290 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
2e2a0 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20  QLITE_UTF8      
2e2b0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
2e2c0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
2e2d0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
2e2e0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
2e2f0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
2e300 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
2e310 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
2e320 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
2e330 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
2e340 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
2e350 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69      5    /* sqli
2e360 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2e370 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  ion only */.#def
2e380 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2e390 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f  _ALIGNED  8    /
2e3a0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
2e3b0 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20  _collation only 
2e3c0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
2e3d0 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46  EF: Deprecated F
2e3e0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52  unctions.** DEPR
2e3f0 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65  ECATED.**.** The
2e400 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
2e410 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20   [deprecated].  
2e420 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
2e430 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
2e440 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
2e450 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
2e460 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2e470 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f   continue .** to
2e480 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20   be supported.  
2e490 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70  However, new app
2e4a0 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
2e4b0 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73   avoid.** the us
2e4c0 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  e of these funct
2e4d0 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65  ions.  To help e
2e4e0 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20  ncourage people 
2e4f0 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e  to avoid.** usin
2e500 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  g these function
2e510 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f  s, we are not go
2e520 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20  ing to tell you 
2e530 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f  what they do..*/
2e540 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
2e550 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a  OMIT_DEPRECATED.
2e560 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2e570 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67  D int sqlite3_ag
2e580 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
2e590 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2e5a0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
2e5b0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  ED int sqlite3_e
2e5c0 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
2e5d0 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
2e5e0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
2e5f0 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69  ite3_transfer_bi
2e600 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
2e610 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74  tmt*, sqlite3_st
2e620 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
2e630 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2e640 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76  te3_global_recov
2e650 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  er(void);.SQLITE
2e660 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
2e670 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
2e680 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
2e690 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2e6a0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d   int sqlite3_mem
2e6b0 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a  ory_alarm(void(*
2e6c0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  )(void*,sqlite3_
2e6d0 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a  int64,int),void*
2e6e0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b  ,sqlite3_int64);
2e6f0 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
2e700 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69  API3REF: Obtaini
2e710 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  ng SQL Function 
2e720 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73  Parameter Values
2e730 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e  .**.** The C-lan
2e740 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61  guage implementa
2e750 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63  tion of SQL func
2e760 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
2e770 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69  ates uses.** thi
2e780 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61  s set of interfa
2e790 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61  ce routines to a
2e7a0 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65  ccess the parame
2e7b0 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a  ter values on.**
2e7c0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72   the function or
2e7d0 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a   aggregate..**.*
2e7e0 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72  * The xFunc (for
2e7f0 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e   scalar function
2e800 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72  s) or xStep (for
2e810 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72   aggregates) par
2e820 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73  ameters.** to [s
2e830 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2e840 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
2e850 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2e860 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64  nction16()].** d
2e870 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20  efine callbacks 
2e880 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
2e890 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  he SQL functions
2e8a0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
2e8b0 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61  .** The 3rd para
2e8c0 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63  meter to these c
2e8d0 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61  allbacks is an a
2e8e0 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
2e8f0 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65   to.** [protecte
2e900 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2e910 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65   objects.  There
2e920 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33   is one [sqlite3
2e930 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
2e940 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d  or.** each param
2e950 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20  eter to the SQL 
2e960 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65  function.  These
2e970 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
2e980 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74  ed to.** extract
2e990 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65   values from the
2e9a0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
2e9b0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20   objects..**.** 
2e9c0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
2e9d0 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70  ork only with [p
2e9e0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2e9f0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
2ea00 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
2ea10 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75  to use these rou
2ea20 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70  tines on an [unp
2ea30 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2ea40 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63  _value].** objec
2ea50 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  t results in und
2ea60 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
2ea70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2ea80 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74  utines work just
2ea90 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73   like the corres
2eaa0 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20  ponding [column 
2eab0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
2eac0 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ].** except that
2ead0 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73    these routines
2eae0 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b   take a single [
2eaf0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2eb00 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a  3_value] object.
2eb10 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65  ** pointer inste
2eb20 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33  ad of a [sqlite3
2eb30 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20  _stmt*] pointer 
2eb40 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63  and an integer c
2eb50 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a  olumn number..**
2eb60 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2eb70 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
2eb80 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
2eb90 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  ts a UTF-16 stri
2eba0 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
2ebb0 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
2ebc0 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
2ebd0 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  ne.  ^The.** sql
2ebe0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2ebf0 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
2ec00 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
2ec10 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
2ec20 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20   extract UTF-16 
2ec30 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65  strings as big-e
2ec40 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65  ndian and little
2ec50 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69  -endian respecti
2ec60 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  vely..**.** ^(Th
2ec70 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
2ec80 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69  numeric_type() i
2ec90 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
2eca0 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75  s to apply.** nu
2ecb0 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74  meric affinity t
2ecc0 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68  o the value.  Th
2ecd0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e  is means that an
2ece0 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d   attempt is.** m
2ecf0 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ade to convert t
2ed00 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69  he value to an i
2ed10 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69  nteger or floati
2ed20 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a  ng point.  If.**
2ed30 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69   such a conversi
2ed40 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77  on is possible w
2ed50 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69  ithout loss of i
2ed60 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f  nformation (in o
2ed70 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69  ther.** words, i
2ed80 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61  f the value is a
2ed90 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f   string that loo
2eda0 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72  ks like a number
2edb0 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ).** then the co
2edc0 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66  nversion is perf
2edd0 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73  ormed.  Otherwis
2ede0 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e no conversion 
2edf0 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b  occurs..** The [
2ee00 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
2ee10 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72   datatype] after
2ee20 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72   conversion is r
2ee30 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  eturned.)^.**.**
2ee40 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74   Please pay part
2ee50 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e  icular attention
2ee60 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61   to the fact tha
2ee70 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65  t the pointer re
2ee80 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
2ee90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
2eea0 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
2eeb0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f  value_text()], o
2eec0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  r.** [sqlite3_va
2eed0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61  lue_text16()] ca
2eee0 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  n be invalidated
2eef0 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74   by a subsequent
2ef00 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2ef10 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2ef20 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
2ef30 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20  lue_bytes16()], 
2ef40 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2ef50 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
2ef60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2ef70 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  t16()]..**.** Th
2ef80 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
2ef90 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
2efa0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
2efb0 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
2efc0 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70  unction that sup
2efd0 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74  plied the [sqlit
2efe0 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d  e3_value*] param
2eff0 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  eters..*/.const 
2f000 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
2f010 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  lue_blob(sqlite3
2f020 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
2f030 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2f040 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  s(sqlite3_value*
2f050 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
2f060 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c  alue_bytes16(sql
2f070 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f  ite3_value*);.do
2f080 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  uble sqlite3_val
2f090 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  ue_double(sqlite
2f0a0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
2f0b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2f0c0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2f0d0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
2f0e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
2f0f0 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64(sqlite3_valu
2f100 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  e*);.const unsig
2f110 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
2f120 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c  3_value_text(sql
2f130 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
2f140 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2f150 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73  3_value_text16(s
2f160 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2f170 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2f180 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2f190 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
2f1a0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
2f1b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2f1c0 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76  xt16be(sqlite3_v
2f1d0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2f1e0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73  te3_value_type(s
2f1f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2f200 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2f210 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
2f220 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2f230 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f240 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
2f250 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
2f260 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65  xt.**.** Impleme
2f270 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72  ntations of aggr
2f280 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2f290 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20  ons use this.** 
2f2a0 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
2f2b0 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73  ate memory for s
2f2c0 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
2f2d0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  te..**.** ^The f
2f2e0 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71  irst time the sq
2f2f0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2f300 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
2f310 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a  tine is called .
2f320 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ** for a particu
2f330 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75  lar aggregate fu
2f340 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a  nction, SQLite.*
2f350 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66  * allocates N of
2f360 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
2f370 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  out that memory,
2f380 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
2f390 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
2f3a0 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e   new memory. ^On
2f3b0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
2f3c0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
2f3d0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
2f3e0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66  gate_context() f
2f3f0 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
2f400 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
2f410 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  nstance,.** the 
2f420 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
2f430 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65  eturned.  Sqlite
2f440 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2f450 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c  ext() is normall
2f460 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65  y.** called once
2f470 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61   for each invoca
2f480 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65  tion of the xSte
2f490 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74  p callback and t
2f4a0 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20  hen one.** last 
2f4b0 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46  time when the xF
2f4c0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73  inal callback is
2f4d0 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65   invoked.  ^(Whe
2f4e0 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a  n no rows match.
2f4f0 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  ** an aggregate 
2f500 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70  query, the xStep
2f510 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  () callback of t
2f520 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
2f530 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ction.** impleme
2f540 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72  ntation is never
2f550 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e   called and xFin
2f560 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65  al() is called e
2f570 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20  xactly once..** 
2f580 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20  In those cases, 
2f590 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2f5a0 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68  e_context() migh
2f5b0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20  t be called for 
2f5c0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d  the.** first tim
2f5d0 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46  e from within xF
2f5e0 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  inal().)^.**.** 
2f5f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67  ^The sqlite3_agg
2f600 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
2f610 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,N) routine retu
2f620 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
2f630 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65  er if N is.** le
2f640 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
2f650 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61   to zero or if a
2f660 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
2f670 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a   error occurs..*
2f680 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e  *.** ^(The amoun
2f690 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63  t of space alloc
2f6a0 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
2f6b0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2f6c0 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74  t(C,N) is.** det
2f6d0 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e  ermined by the N
2f6e0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69   parameter on fi
2f6f0 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63  rst successful c
2f700 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74  all.  Changing t
2f710 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e  he.** value of N
2f720 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
2f730 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  all to sqlite3_a
2f740 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2f750 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  () within.** the
2f760 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
2f770 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63  function instanc
2f780 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a  e will not resiz
2f790 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  e the memory.** 
2f7a0 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a  allocation.)^.**
2f7b0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f  .** ^SQLite auto
2f7c0 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20  matically frees 
2f7d0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
2f7e0 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  ated by .** sqli
2f7f0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2f800 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65  ntext() when the
2f810 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
2f820 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a   concludes..**.*
2f830 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
2f840 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20  meter must be a 
2f850 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  copy of the.** [
2f860 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
2f870 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
2f880 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
2f890 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
2f8a0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53  ter.** to the xS
2f8b0 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  tep or xFinal ca
2f8c0 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
2f8d0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
2f8e0 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
2f8f0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2f900 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
2f910 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
2f920 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
2f930 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
2f940 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
2f950 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
2f960 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
2f970 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2f980 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  ontext(sqlite3_c
2f990 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79  ontext*, int nBy
2f9a0 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tes);../*.** CAP
2f9b0 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61  I3REF: User Data
2f9c0 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
2f9d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2f9e0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e  3_user_data() in
2f9f0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2fa00 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
2fa10 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61   pointer that wa
2fa20 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20  s the pUserData 
2fa30 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35  parameter (the 5
2fa40 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  th parameter).**
2fa50 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
2fa60 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2fa70 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
2fa80 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2fa90 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
2faa0 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
2fab0 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
2fac0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2fad0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2fae0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
2faf0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
2fb00 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
2fb10 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
2fb20 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  h.** the applica
2fb30 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2fb40 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
2fb50 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
2fb60 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c  e3_user_data(sql
2fb70 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
2fb80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2fb90 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
2fba0 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f  tion For Functio
2fbb0 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
2fbc0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
2fbd0 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66  _handle() interf
2fbe0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
2fbf0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
2fc00 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
2fc10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2fc20 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d  ] (the 1st param
2fc30 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
2fc40 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2fc50 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
2fc60 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2fc70 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2fc80 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
2fc90 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
2fca0 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
2fcb0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
2fcc0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c  function..*/.sql
2fcd0 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f  ite3 *sqlite3_co
2fce0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
2fcf0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2fd00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2fd10 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
2fd20 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a  iliary Data.**.*
2fd30 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
2fd40 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  two functions ma
2fd50 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61  y be used by sca
2fd60 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
2fd70 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
2fd80 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
2fd90 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
2fda0 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
2fdb0 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
2fdc0 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
2fdd0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
2fde0 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
2fdf0 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
2fe00 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
2fe10 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
2fe20 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
2fe30 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
2fe40 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54   be preserved. T
2fe50 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73  his may.** be us
2fe60 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  ed, for example,
2fe70 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61   to add a regula
2fe80 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
2fe90 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20  ching scalar.** 
2fea0 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
2feb0 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
2fec0 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
2fed0 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72  pression is stor
2fee0 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74  ed as.** metadat
2fef0 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
2ff00 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20  h the SQL value 
2ff10 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65  passed as the re
2ff20 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
2ff30 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68  .** pattern.  Th
2ff40 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c  e compiled regul
2ff50 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
2ff60 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d  n be reused on m
2ff70 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63  ultiple.** invoc
2ff80 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2ff90 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74  me function so t
2ffa0 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  hat the original
2ffb0 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a   pattern string.
2ffc0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ** does not need
2ffd0 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65   to be recompile
2ffe0 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61  d on each invoca
2fff0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
30000 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
30010 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
30020 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
30030 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61  er to the metada
30040 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
30050 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
30060 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75  set_auxdata() fu
30070 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
30080 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  Nth argument.** 
30090 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70  value to the app
300a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
300b0 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e   function. ^If n
300c0 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62  o metadata has b
300d0 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e  een ever.** been
300e0 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68   set for the Nth
300f0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
30100 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66   function, or if
30110 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
30120 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  ng.** function p
30130 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61  arameter has cha
30140 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d  nged since the m
30150 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74  eta-data was set
30160 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65  ,.** then sqlite
30170 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
30180 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
30190 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
301a0 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
301b0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
301c0 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74  ce saves the met
301d0 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64  adata.** pointed
301e0 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70   to by its 3rd p
301f0 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
30200 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
30210 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
30220 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
30230 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
30240 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65  ction.  Subseque
30250 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  nt.** calls to s
30260 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
30270 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72  ta() might retur
30280 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20  n this data, if 
30290 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65  it has.** not be
302a0 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  en destroyed..**
302b0 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e   ^If it is not N
302c0 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  ULL, SQLite will
302d0 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
302e0 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69  ructor.** functi
302f0 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20  on given by the 
30300 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
30310 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
30320 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65  data() on.** the
30330 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74   metadata when t
30340 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
30350 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
30360 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  ter changes.** o
30370 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73  r when the SQL s
30380 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74  tatement complet
30390 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  es, whichever co
303a0 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a  mes first..**.**
303b0 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20   SQLite is free 
303c0 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74  to call the dest
303d0 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20  ructor and drop 
303e0 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a  metadata on any.
303f0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ** parameter of 
30400 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20  any function at 
30410 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20  any time.  ^The 
30420 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69  only guarantee i
30430 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65  s that.** the de
30440 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65  structor will be
30450 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74   called before t
30460 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64  he metadata is d
30470 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ropped..**.** ^(
30480 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74  In practice, met
30490 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76  adata is preserv
304a0 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74  ed between funct
304b0 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a  ion calls for.**
304c0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61   expressions tha
304d0 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61  t are constant a
304e0 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  t compile time. 
304f0 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69  This includes li
30500 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20  teral.** values 
30510 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d  and [parameters]
30520 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  .)^.**.** These 
30530 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
30540 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
30550 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
30560 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c  which.** the SQL
30570 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
30580 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
30590 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
305a0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
305b0 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69  xt*, int N);.voi
305c0 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  d sqlite3_set_au
305d0 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
305e0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76  ntext*, int N, v
305f0 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76  oid*, void (*)(v
30600 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  oid*));.../*.** 
30610 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61  CAPI3REF: Consta
30620 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65  nts Defining Spe
30630 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20  cial Destructor 
30640 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54  Behavior.**.** T
30650 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
30660 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20   values for the 
30670 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
30680 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
30690 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
306a0 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
306b0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
306c0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
306d0 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63   ^If the destruc
306e0 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  tor.** argument 
306f0 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  is SQLITE_STATIC
30700 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
30710 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e  the content poin
30720 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a  ter is constant.
30730 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65  ** and will neve
30740 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f  r change.  It do
30750 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
30760 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54  e destroyed.  ^T
30770 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41  he.** SQLITE_TRA
30780 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61  NSIENT value mea
30790 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
307a0 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ent will likely 
307b0 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65  change in.** the
307c0 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64   near future and
307d0 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f   that SQLite sho
307e0 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e  uld make its own
307f0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
30800 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
30810 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
30820 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65  ..**.** The type
30830 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79  def is necessary
30840 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20   to work around 
30850 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74  problems in cert
30860 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69  ain.** C++ compi
30870 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65  lers.  See ticke
30880 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65  t #2191..*/.type
30890 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
308a0 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
308b0 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66  pe)(void*);.#def
308c0 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ine SQLITE_STATI
308d0 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33  C      ((sqlite3
308e0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
308f0 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  )0).#define SQLI
30900 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28  TE_TRANSIENT   (
30910 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
30920 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a  tor_type)-1)../*
30930 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
30940 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74  tting The Result
30950 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74   Of An SQL Funct
30960 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ion.**.** These 
30970 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
30980 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f  d by the xFunc o
30990 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
309a0 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65  ks that.** imple
309b0 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  ment SQL functio
309c0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
309d0 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69  s.  See.** [sqli
309e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
309f0 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
30a00 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
30a10 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20  ion16()].** for 
30a20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
30a30 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
30a40 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f  ese functions wo
30a50 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b  rk very much lik
30a60 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72  e the [parameter
30a70 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79   binding] family
30a80 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   of.** functions
30a90 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61   used to bind va
30aa0 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
30ab0 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61  ameters in prepa
30ac0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  red statements..
30ad0 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20  ** Refer to the 
30ae0 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
30af0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
30b00 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
30b10 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
30b20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
30b30 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72  ult_blob() inter
30b40 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
30b50 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
30b60 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
30b70 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
30b80 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73  be the BLOB whos
30b90 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69  e content is poi
30ba0 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68  nted.** to by th
30bb0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
30bc0 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20  er and which is 
30bd0 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65  N bytes long whe
30be0 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74  re N is the.** t
30bf0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a  hird parameter..
30c00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
30c10 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
30c20 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  ob() interfaces 
30c30 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f  set the result o
30c40 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
30c50 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
30c60 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c  ction to be a BL
30c70 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c  OB containing al
30c80 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20  l zero.** bytes 
30c90 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73  and N bytes in s
30ca0 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ize, where N is 
30cb0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
30cc0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a   2nd parameter..
30cd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
30ce0 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
30cf0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
30d00 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
30d10 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
30d20 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
30d30 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f  tion to be a flo
30d40 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
30d50 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
30d60 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  y its 2nd argume
30d70 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
30d80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
30d90 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
30da0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
30db0 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  () functions.** 
30dc0 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d  cause the implem
30dd0 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69  ented SQL functi
30de0 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  on to throw an e
30df0 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51  xception..** ^SQ
30e00 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74  Lite uses the st
30e10 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20  ring pointed to 
30e20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61  by the.** 2nd pa
30e30 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74  rameter of sqlit
30e40 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
30e50 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  ) or sqlite3_res
30e60 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
30e70 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20   as the text of 
30e80 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
30e90 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72  .  ^SQLite inter
30ea0 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a  prets the error.
30eb0 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  ** message strin
30ec0 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
30ed0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73  esult_error() as
30ee0 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a   UTF-8. ^SQLite.
30ef0 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  ** interprets th
30f00 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
30f10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
30f20 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36  or16() as UTF-16
30f30 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79   in native.** by
30f40 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74  te order.  ^If t
30f50 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
30f60 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
30f70 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
30f80 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
30f90 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e  t_error16() is n
30fa0 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
30fb0 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65  ite takes as the
30fc0 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
30fd0 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68  e all text up th
30fe0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
30ff0 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
31000 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  ** ^If the third
31010 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
31020 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
31030 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  or() or.** sqlit
31040 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
31050 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  6() is non-negat
31060 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
31070 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a  takes that many.
31080 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ** bytes (not ch
31090 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74  aracters) from t
310a0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
310b0 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65   as the error me
310c0 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73  ssage..** ^The s
310d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
310e0 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
310f0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
31100 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d  ().** routines m
31110 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f  ake a private co
31120 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  py of the error 
31130 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66  message text bef
31140 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75  ore.** they retu
31150 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  rn.  Hence, the 
31160 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
31170 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20   can deallocate 
31180 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65  or.** modify the
31190 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79   text after they
311a0 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20   return without 
311b0 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  harm..** ^The sq
311c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
311d0 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69  or_code() functi
311e0 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65  on changes the e
311f0 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74  rror code.** ret
31200 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20  urned by SQLite 
31210 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61  as a result of a
31220 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e  n error in a fun
31230 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61  ction.  ^By defa
31240 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f  ult,.** the erro
31250 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45  r code is SQLITE
31260 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73  _ERROR.  ^A subs
31270 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73  equent call to s
31280 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31290 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
312a0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
312b0 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20  16() resets the 
312c0 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51  error code to SQ
312d0 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a  LITE_ERROR..**.*
312e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
312f0 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69  esult_toobig() i
31300 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
31310 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
31320 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69  an error.** indi
31330 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74  cating that a st
31340 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20  ring or BLOB is 
31350 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72  too long to repr
31360 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  esent..**.** ^Th
31370 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
31380 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61  _nomem() interfa
31390 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
313a0 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72   to throw an err
313b0 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  or.** indicating
313c0 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61   that a memory a
313d0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64  llocation failed
313e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
313f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
31400 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
31410 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
31420 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
31430 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
31440 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
31450 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64  he 32-bit signed
31460 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
31470 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
31480 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  nd argument..** 
31490 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
314a0 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65  ult_int64() inte
314b0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
314c0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
314d0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
314e0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
314f0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d  on to be the 64-
31500 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
31510 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
31520 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
31530 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
31540 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
31550 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  _null() interfac
31560 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
31570 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
31580 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
31590 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
315a0 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  o be NULL..**.**
315b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
315c0 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c  sult_text(), sql
315d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
315e0 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  16(),.** sqlite3
315f0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
31600 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
31610 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
31620 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
31630 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76  set the return v
31640 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c  alue of the appl
31650 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
31660 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  function to be.*
31670 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20  * a text string 
31680 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65  which is represe
31690 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55  nted as UTF-8, U
316a0 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
316b0 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d  e order,.** UTF-
316c0 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e  16 little endian
316d0 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20  , or UTF-16 big 
316e0 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69  endian, respecti
316f0 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  vely..** ^SQLite
31700 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20   takes the text 
31710 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20  result from the 
31720 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d  application from
31730 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61  .** the 2nd para
31740 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c  meter of the sql
31750 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
31760 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  * interfaces..**
31770 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
31780 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
31790 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
317a0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
317b0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
317c0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
317d0 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d  result text from
317e0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
317f0 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68  er.** through th
31800 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
31810 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  racter..** ^If t
31820 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
31830 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
31840 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
31850 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f  erfaces.** is no
31860 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
31870 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28   as many bytes (
31880 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
31890 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70  of the text.** p
318a0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
318b0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
318c0 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20  re taken as the 
318d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
318e0 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ned.** function 
318f0 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20  result.  If the 
31900 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  3rd parameter is
31910 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
31920 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62  hen it.** must b
31930 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
31940 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e  t into the strin
31950 67 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20  g where the NUL 
31960 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64  terminator would
31970 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74 68  .** appear if th
31980 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e  e string where N
31990 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  UL terminated.  
319a0 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61  If any NUL chara
319b0 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69  cters occur.** i
319c0 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61 74 20  n the string at 
319d0 61 20 62 79 74 65 20 6f 66 66 73 65 74 20 74 68  a byte offset th
319e0 61 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  at is less than 
319f0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
31a00 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65   3rd.** paramete
31a10 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  r, then the resu
31a20 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c  lting string wil
31a30 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64  l contain embedd
31a40 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a  ed NULs and the.
31a50 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70  ** result of exp
31a60 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69  ressions operati
31a70 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69  ng on strings wi
31a80 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  th embedded NULs
31a90 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
31aa0 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
31ab0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
31ac0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31ad0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
31ae0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
31af0 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f  ult_blob is a no
31b00 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
31b10 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c  then SQLite call
31b20 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69  s that.** functi
31b30 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75  on as the destru
31b40 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74  ctor on the text
31b50 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
31b60 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66  when it has.** f
31b70 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
31b80 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
31b90 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
31ba0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
31bb0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
31bc0 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f  interfaces or to
31bd0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
31be0 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
31bf0 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
31c00 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
31c10 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73  hen SQLite.** as
31c20 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74  sumes that the t
31c30 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
31c40 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e  lt is in constan
31c50 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  t space and does
31c60 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65   not.** copy the
31c70 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
31c80 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61  parameter nor ca
31c90 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ll a destructor 
31ca0 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a  on the content.*
31cb0 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  * when it has fi
31cc0 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
31cd0 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
31ce0 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
31cf0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
31d00 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
31d10 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
31d20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
31d30 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
31d40 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
31d50 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20  TE_TRANSIENT.** 
31d60 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65  then SQLite make
31d70 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
31d80 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63  result into spac
31d90 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a  e obtained from.
31da0 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
31db0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72  _malloc()] befor
31dc0 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
31dd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31de0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
31df0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
31e00 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
31e10 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
31e20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
31e30 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68   to be a copy th
31e40 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  e.** [unprotecte
31e50 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
31e60 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
31e70 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  d by the 2nd par
31e80 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a  ameter.  ^The.**
31e90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31ea0 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
31eb0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
31ec0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
31ed0 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74  alue].** so that
31ee0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
31ef0 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69  lue] specified i
31f00 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
31f10 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a  may change or.**
31f20 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
31f30 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65  after sqlite3_re
31f40 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74  sult_value() ret
31f50 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72  urns without har
31f60 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63  m..** ^A [protec
31f70 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
31f80 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c  e] object may al
31f90 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65  ways be used whe
31fa0 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  re an.** [unprot
31fb0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
31fc0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72  lue] object is r
31fd0 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68  equired, so eith
31fe0 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73  er.** kind of [s
31ff0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
32000 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64  ject can be used
32010 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72   with this inter
32020 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  face..**.** If t
32030 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
32040 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69  e called from wi
32050 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65  thin the differe
32060 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61  nt thread.** tha
32070 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69  n the one contai
32080 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61  ning the applica
32090 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
320a0 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69  ction that recei
320b0 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ved.** the [sqli
320c0 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69  te3_context] poi
320d0 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74  nter, the result
320e0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
320f0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
32100 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c  _result_blob(sql
32110 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
32120 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
32130 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
32140 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
32150 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c  esult_double(sql
32160 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64  ite3_context*, d
32170 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c  ouble);.void sql
32180 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32190 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  r(sqlite3_contex
321a0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
321b0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
321c0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
321d0 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
321e0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
321f0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
32200 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32210 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33  r_toobig(sqlite3
32220 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
32230 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32240 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69  error_nomem(sqli
32250 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
32260 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
32270 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71  lt_error_code(sq
32280 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
32290 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
322a0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71  e3_result_int(sq
322b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
322c0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
322d0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
322e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
322f0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
32300 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
32310 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74  esult_null(sqlit
32320 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
32330 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
32340 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  t_text(sqlite3_c
32350 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
32360 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  har*, int, void(
32370 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
32380 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32390 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63  text16(sqlite3_c
323a0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
323b0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
323c0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
323d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
323e0 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
323f0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
32400 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
32410 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
32420 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
32430 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
32440 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
32450 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
32460 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
32470 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
32480 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  t_value(sqlite3_
32490 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
324a0 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20  3_value*);.void 
324b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
324c0 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
324d0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29  context*, int n)
324e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
324f0 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f  F: Define New Co
32500 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65  llating Sequence
32510 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  s.**.** ^These f
32520 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65  unctions add, re
32530 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20  move, or modify 
32540 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73  a [collation] as
32550 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
32560 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
32570 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
32580 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73  fied as the firs
32590 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
325a0 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
325b0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20  he collation is 
325c0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  a UTF-8 string.*
325d0 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
325e0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
325f0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65   and sqlite3_cre
32600 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
32610 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d  ().** and a UTF-
32620 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
32630 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66  ive byte order f
32640 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
32650 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
32660 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e  .** ^Collation n
32670 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72  ames that compar
32680 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e  e equal accordin
32690 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  g to [sqlite3_st
326a0 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a  rnicmp()] are.**
326b0 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62   considered to b
326c0 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e  e the same name.
326d0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69  .**.** ^(The thi
326e0 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65  rd argument (eTe
326f0 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f  xtRep) must be o
32700 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61  ne of the consta
32710 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  nts:.** <ul>.** 
32720 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
32730 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8],.** <li> [SQL
32740 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a  ITE_UTF16LE],.**
32750 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
32760 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  F16BE],.** <li> 
32770 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
32780 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
32790 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
327a0 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  ]..** </ul>)^.**
327b0 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61   ^The eTextRep a
327c0 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e  rgument determin
327d0 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  es the encoding 
327e0 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65  of strings passe
327f0 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c  d.** to the coll
32800 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
32810 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61  allback, xCallba
32820 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  ck..** ^The [SQL
32830 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b  ITE_UTF16] and [
32840 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
32850 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72  GNED] values for
32860 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72   eTextRep.** for
32870 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65  ce strings to be
32880 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69   UTF16 with nati
32890 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
328a0 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55  * ^The [SQLITE_U
328b0 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61  TF16_ALIGNED] va
328c0 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70  lue for eTextRep
328d0 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20   forces strings 
328e0 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61  to begin.** on a
328f0 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72  n even byte addr
32900 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ess..**.** ^The 
32910 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
32920 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70   pArg, is an app
32930 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
32940 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61  inter that is pa
32950 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20  ssed.** through 
32960 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
32970 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c  ument to the col
32980 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
32990 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
329a0 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d  ^The fifth argum
329b0 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20  ent, xCallback, 
329c0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
329d0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
329e0 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74  nction..** ^Mult
329f0 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66  iple collating f
32a00 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20  unctions can be 
32a10 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
32a20 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
32a30 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65  ut.** with diffe
32a40 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 61  rent eTextRep pa
32a50 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c  rameters and SQL
32a60 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69  ite will use whi
32a70 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69  chever.** functi
32a80 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 20  on requires the 
32a90 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
32aa0 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74  data transformat
32ab0 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ion..** ^If the 
32ac0 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65  xCallback argume
32ad0 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  nt is NULL then 
32ae0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
32af0 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c  nction is.** del
32b00 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c  eted.  ^When all
32b10 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
32b20 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20  ions having the 
32b30 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65  same name are de
32b40 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63  leted,.** that c
32b50 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c  ollation is no l
32b60 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a  onger usable..**
32b70 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69  .** ^The collati
32b80 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  ng function call
32b90 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
32ba0 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74  with a copy of t
32bb0 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c  he pArg .** appl
32bc0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
32bd0 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 77  nter and with tw
32be0 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65  o strings in the
32bf0 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66   encoding specif
32c00 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54  ied.** by the eT
32c10 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e  extRep argument.
32c20 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20    The collating 
32c30 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65  function must re
32c40 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  turn an.** integ
32c50 65 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 74  er that is negat
32c60 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f  ive, zero, or po
32c70 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65  sitive.** if the
32c80 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73   first string is
32c90 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61   less than, equa
32ca0 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72  l to, or greater
32cb0 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64   than the second
32cc0 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ,.** respectivel
32cd0 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20  y.  A collating 
32ce0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c  function must al
32cf0 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20  ways return the 
32d00 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67  same answer.** g
32d10 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e  iven the same in
32d20 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72  puts.  If two or
32d30 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20   more collating 
32d40 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65  functions are re
32d50 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74  gistered.** to t
32d60 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f  he same collatio
32d70 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69  n name (using di
32d80 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70  fferent eTextRep
32d90 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c   values) then al
32da0 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61  l.** must give a
32db0 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73  n equivalent ans
32dc0 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64  wer when invoked
32dd0 20 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74   with equivalent
32de0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
32df0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
32e00 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68  ion must obey th
32e10 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70  e following prop
32e20 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a  erties for all.*
32e30 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20  * strings A, B, 
32e40 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c  and C:.**.** <ol
32e50 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d  >.** <li> If A==
32e60 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20  B then B==A..** 
32e70 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64  <li> If A==B and
32e80 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e   B==C then A==C.
32e90 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74  .** <li> If A&lt
32ea0 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a  ;B THEN B&gt;A..
32eb0 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b  ** <li> If A&lt;
32ec0 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65  B and B&lt;C the
32ed0 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f  n A&lt;C..** </o
32ee0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f  l>.**.** If a co
32ef0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
32f00 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68   fails any of th
32f10 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69  e above constrai
32f20 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20  nts and that.** 
32f30 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
32f40 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65 72 65  on is  registere
32f50 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e  d and used, then
32f60 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
32f70 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e   SQLite.** is un
32f80 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
32f90 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  The sqlite3_crea
32fa0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
32fb0 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  ) works like sql
32fc0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
32fd0 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20  ation().** with 
32fe0 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61  the addition tha
32ff0 74 20 74 68 65 20 78 44 65 73 74 72 6f 79 20 63  t the xDestroy c
33000 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
33010 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a  ed on pArg when.
33020 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  ** the collating
33030 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c   function is del
33040 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74  eted..** ^Collat
33050 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ing functions ar
33060 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74  e deleted when t
33070 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64  hey are overridd
33080 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63  en by later.** c
33090 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c  alls to the coll
330a0 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66  ation creation f
330b0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e  unctions or when
330c0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
330d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
330e0 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73   closed using [s
330f0 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e  qlite3_close()].
33100 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73  .**.** ^The xDes
33110 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  troy callback is
33120 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c   <u>not</u> call
33130 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71  ed if the .** sq
33140 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
33150 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63  lation_v2() func
33160 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70  tion fails.  App
33170 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69  lications that i
33180 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
33190 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
331a0 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f  n_v2() with a no
331b0 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20  n-NULL xDestroy 
331c0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
331d0 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65  .** check the re
331e0 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69  turn code and di
331f0 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70  spose of the app
33200 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
33210 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c  inter.** themsel
33220 76 65 73 20 72 61 74 68 65 72 20 74 68 61 6e 20  ves rather than 
33230 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65  expecting SQLite
33240 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74   to deal with it
33250 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68   for them..** Th
33260 69 73 20 69 73 20 64 69 66 66 65 72 65 6e 74 20  is is different 
33270 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72  from every other
33280 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
33290 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73  e.  The inconsis
332a0 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66  tency .** is unf
332b0 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e  ortunate but can
332c0 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 77  not be changed w
332d0 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
332e0 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f  backwards .** co
332f0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
33300 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73  ** See also:  [s
33310 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
33320 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b  _needed()] and [
33330 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
33340 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a  n_needed16()]..*
33350 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
33360 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a  eate_collation(.
33370 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
33380 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
33390 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
333a0 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67  p, .  void *pArg
333b0 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
333c0 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
333d0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
333e0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74  st void*).);.int
333f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
33400 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20  collation_v2(.  
33410 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
33420 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
33430 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
33440 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
33450 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
33460 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
33470 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
33480 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28   void*),.  void(
33490 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
334a0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
334b0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
334c0 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  n16(.  sqlite3*,
334d0 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a   .  const void *
334e0 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65  zName,.  int eTe
334f0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a  xtRep, .  void *
33500 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  pArg,.  int(*xCo
33510 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
33520 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
33530 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
33540 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33550 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64  : Collation Need
33560 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  ed Callbacks.**.
33570 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76  ** ^To avoid hav
33580 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20  ing to register 
33590 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  all collation se
335a0 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61  quences before a
335b0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e   database.** can
335c0 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67   be used, a sing
335d0 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  le callback func
335e0 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69  tion may be regi
335f0 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a  stered with the.
33600 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
33610 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69  nection] to be i
33620 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
33630 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  an undefined col
33640 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
33650 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a  ce is required..
33660 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75  **.** ^If the fu
33670 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74  nction is regist
33680 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
33690 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
336a0 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a  _needed() API,.*
336b0 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73  * then it is pas
336c0 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  sed the names of
336d0 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
336e0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61  tion sequences a
336f0 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63  s strings.** enc
33700 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e  oded in UTF-8. ^
33710 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  If sqlite3_colla
33720 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20  tion_needed16() 
33730 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20  is used,.** the 
33740 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64  names are passed
33750 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61   as UTF-16 in ma
33760 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74  chine native byt
33770 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63  e order..** ^A c
33780 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75  all to either fu
33790 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20  nction replaces 
337a0 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c  the existing col
337b0 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61  lation-needed ca
337c0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28  llback..**.** ^(
337d0 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
337e0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68  k is invoked, th
337f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
33800 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70   passed is a cop
33810 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f  y.** of the seco
33820 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
33830 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
33840 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20  _needed() or.** 
33850 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
33860 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54  n_needed16().  T
33870 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
33880 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61  nt is the databa
33890 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
338a0 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
338b0 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
338c0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b  [SQLITE_UTF8], [
338d0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
338e0 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
338f0 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74  TF16LE], indicat
33900 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73  ing the most des
33910 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74  irable form of t
33920 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  he collation.** 
33930 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f  sequence functio
33940 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65  n required.  The
33950 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
33960 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
33970 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64   the.** required
33980 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
33990 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  nce.)^.**.** The
339a0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
339b0 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74  on should regist
339c0 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63  er the desired c
339d0 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  ollation using.*
339e0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
339f0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20  e_collation()], 
33a00 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
33a10 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20  collation16()], 
33a20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  or.** [sqlite3_c
33a30 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
33a40 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  v2()]..*/.int sq
33a50 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
33a60 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65  needed(.  sqlite
33a70 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20  3*, .  void*, . 
33a80 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
33a90 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
33aa0 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a  tRep,const char*
33ab0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
33ac0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
33ad0 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  d16(.  sqlite3*,
33ae0 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69   .  void*,.  voi
33af0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
33b00 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
33b10 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
33b20 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  ..#ifdef SQLITE_
33b30 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20  HAS_CODEC./*.** 
33b40 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20  Specify the key 
33b50 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64  for an encrypted
33b60 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73   database.  This
33b70 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20   routine should 
33b80 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67  be.** called rig
33b90 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ht after sqlite3
33ba0 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  _open()..**.** T
33bb0 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
33bc0 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
33bd0 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
33be0 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
33bf0 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
33c00 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
33c10 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  3_key(.  sqlite3
33c20 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
33c30 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
33c40 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
33c50 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
33c60 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
33c70 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79  y     /* The key
33c80 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68   */.);../*.** Ch
33c90 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20  ange the key on 
33ca0 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  an open database
33cb0 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e  .  If the curren
33cc0 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f  t database is no
33cd0 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20  t.** encrypted, 
33ce0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
33cf0 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49  l encrypt it.  I
33d00 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65  f pNew==0 or nNe
33d10 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74  w==0, the.** dat
33d20 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74  abase is decrypt
33d30 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ed..**.** The co
33d40 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
33d50 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
33d60 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
33d70 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
33d80 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
33d90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b  .int sqlite3_rek
33da0 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
33db0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
33dc0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
33dd0 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
33de0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
33df0 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
33e00 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65     /* The new ke
33e10 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53  y */.);../*.** S
33e20 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76  pecify the activ
33e30 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20  ation key for a 
33e40 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 55  SEE database.  U
33e50 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61  nless .** activa
33e60 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65  ted, none of the
33e70 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69   SEE routines wi
33e80 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64  ll work..*/.void
33e90 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74   sqlite3_activat
33ea0 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63  e_see(.  const c
33eb0 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65  har *zPassPhrase
33ec0 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76          /* Activ
33ed0 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a  ation phrase */.
33ee0 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65  );.#endif..#ifde
33ef0 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f  f SQLITE_ENABLE_
33f00 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63  CEROD./*.** Spec
33f10 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69  ify the activati
33f20 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52  on key for a CER
33f30 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e  OD database.  Un
33f40 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74  less .** activat
33f50 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20  ed, none of the 
33f60 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77  CEROD routines w
33f70 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69  ill work..*/.voi
33f80 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61  d sqlite3_activa
33f90 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73  te_cerod(.  cons
33fa0 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72  t char *zPassPhr
33fb0 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63  ase        /* Ac
33fc0 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20  tivation phrase 
33fd0 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  */.);.#endif../*
33fe0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75  .** CAPI3REF: Su
33ff0 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20  spend Execution 
34000 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65  For A Short Time
34010 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
34020 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74  e3_sleep() funct
34030 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63  ion causes the c
34040 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f  urrent thread to
34050 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
34060 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61  on.** for at lea
34070 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d  st a number of m
34080 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63  illiseconds spec
34090 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72  ified in its par
340a0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
340b0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
340c0 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73  ystem does not s
340d0 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71  upport sleep req
340e0 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69  uests with.** mi
340f0 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72  llisecond time r
34100 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20  esolution, then 
34110 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65  the time will be
34120 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a   rounded up to.*
34130 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65  * the nearest se
34140 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72  cond. The number
34150 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
34160 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c   of sleep actual
34170 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  ly.** requested 
34180 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69  from the operati
34190 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74  ng system is ret
341a0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  urned..**.** ^SQ
341b0 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
341c0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62  this interface b
341d0 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53  y calling the xS
341e0 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  leep().** method
341f0 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
34200 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
34210 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 78 53  ject.  If the xS
34220 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a  leep() method.**
34230 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
34240 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65  VFS is not imple
34250 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79  mented correctly
34260 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  , or not impleme
34270 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20  nted at.** all, 
34280 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
34290 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65  r of sqlite3_sle
342a0 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 74 65  ep() may deviate
342b0 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69   from the descri
342c0 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  ption.** in the 
342d0 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
342e0 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  phs..*/.int sqli
342f0 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a  te3_sleep(int);.
34300 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34310 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c   Name Of The Fol
34320 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70  der Holding Temp
34330 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a  orary Files.**.*
34340 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62  * ^(If this glob
34350 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  al variable is m
34360 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
34370 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  a string which i
34380 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
34390 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61   a folder (a.k.a
343a0 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68  . directory), th
343b0 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79  en all temporary
343c0 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65   files.** create
343d0 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e  d by SQLite when
343e0 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69   using a built-i
343f0 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  n [sqlite3_vfs |
34400 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65   VFS].** will be
34410 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20   placed in that 
34420 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49  directory.)^  ^I
34430 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  f this variable.
34440 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
34450 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
34460 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61  e performs a sea
34470 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f  rch for an appro
34480 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  priate.** tempor
34490 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f  ary file directo
344a0 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ry..**.** It is 
344b0 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
344c0 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
344d0 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65  variable in more
344e0 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72   than one.** thr
344f0 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20  ead at a time.  
34500 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
34510 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
34520 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
34530 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65  * if a [database
34540 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
34550 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68  being used at th
34560 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61  e same time in a
34570 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72   separate.** thr
34580 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e  ead..** It is in
34590 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73  tended that this
345a0 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74   variable be set
345b0 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74   once.** as part
345c0 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74   of process init
345d0 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62  ialization and b
345e0 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65  efore any SQLite
345f0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f   interface.** ro
34600 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e  utines have been
34610 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74   called and that
34620 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72   this variable r
34630 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a  emain unchanged.
34640 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a  ** thereafter..*
34650 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f  *.** ^The [temp_
34660 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
34670 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69  pragma] may modi
34680 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
34690 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74   and cause.** it
346a0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
346b0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
346c0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
346d0 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72  c].  ^Furthermor
346e0 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f  e,.** the [temp_
346f0 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
34700 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61  pragma] always a
34710 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20  ssumes that any 
34720 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74  string.** that t
34730 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69  his variable poi
34740 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69  nts to is held i
34750 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  n memory obtaine
34760 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
34770 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20  te3_malloc] and 
34780 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61  the pragma may a
34790 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74  ttempt to free t
347a0 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73  hat memory.** us
347b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
347c0 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66  e]..** Hence, if
347d0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
347e0 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63  s modified direc
347f0 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73  tly, either it s
34800 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65  hould be.** made
34810 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f   NULL or made to
34820 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79   point to memory
34830 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
34840 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a  sqlite3_malloc].
34850 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75  ** or else the u
34860 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f  se of the [temp_
34870 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
34880 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62  pragma] should b
34890 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51  e avoided..*/.SQ
348a0 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72  LITE_EXTERN char
348b0 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64   *sqlite3_temp_d
348c0 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a  irectory;../*.**
348d0 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20   CAPI3REF: Test 
348e0 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20  For Auto-Commit 
348f0 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  Mode.** KEYWORDS
34900 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  : {autocommit mo
34910 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  de}.**.** ^The s
34920 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
34930 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63  ommit() interfac
34940 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  e returns non-ze
34950 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66  ro or.** zero if
34960 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62   the given datab
34970 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
34980 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61  s or is not in a
34990 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a  utocommit mode,.
349a0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
349b0 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f    ^Autocommit mo
349c0 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61  de is on by defa
349d0 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d  ult..** ^Autocom
349e0 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61  mit mode is disa
349f0 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e  bled by a [BEGIN
34a00 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
34a10 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  ^Autocommit mode
34a20 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62   is re-enabled b
34a30 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20  y a [COMMIT] or 
34a40 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a  [ROLLBACK]..**.*
34a50 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e  * If certain kin
34a60 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63  ds of errors occ
34a70 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e  ur on a statemen
34a80 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69  t within a multi
34a90 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72  -statement.** tr
34aa0 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72  ansaction (error
34ab0 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c  s including [SQL
34ac0 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49  ITE_FULL], [SQLI
34ad0 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53  TE_IOERR],.** [S
34ae0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53  QLITE_NOMEM], [S
34af0 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64  QLITE_BUSY], and
34b00 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
34b10 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a  PT]) then the.**
34b20 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67   transaction mig
34b30 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ht be rolled bac
34b40 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
34b50 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74    The only way t
34b60 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68  o.** find out wh
34b70 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74  ether SQLite aut
34b80 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
34b90 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  d back the trans
34ba0 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20  action after.** 
34bb0 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75  an error is to u
34bc0 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  se this function
34bd0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68  ..**.** If anoth
34be0 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65  er thread change
34bf0 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74  s the autocommit
34c00 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64   status of the d
34c10 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
34c20 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73  ction while this
34c30 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e   routine is runn
34c40 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
34c50 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73  turn value.** is
34c60 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69   undefined..*/.i
34c70 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  nt sqlite3_get_a
34c80 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65  utocommit(sqlite
34c90 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
34ca0 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44  3REF: Find The D
34cb0 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f  atabase Handle O
34cc0 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
34cd0 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  tement.**.** ^Th
34ce0 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e  e sqlite3_db_han
34cf0 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 65  dle interface re
34d00 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62  turns the [datab
34d10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
34d20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69  handle.** to whi
34d30 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ch a [prepared s
34d40 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67  tatement] belong
34d50 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61  s.  ^The [databa
34d60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
34d70 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
34d80 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
34d90 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  is the same [dat
34da0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34db0 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68  ].** that was th
34dc0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
34dd0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
34de0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
34df0 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76  ] call (or its v
34e00 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 61  ariants) that wa
34e10 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65  s used to.** cre
34e20 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
34e30 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70  t in the first p
34e40 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  lace..*/.sqlite3
34e50 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e   *sqlite3_db_han
34e60 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dle(sqlite3_stmt
34e70 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
34e80 52 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20  REF: Return The 
34e90 46 69 6c 65 6e 61 6d 65 20 46 6f 72 20 41 20 44  Filename For A D
34ea0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
34eb0 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  on.**.** ^The sq
34ec0 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d  lite3_db_filenam
34ed0 65 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  e(D,N) interface
34ee0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
34ef0 65 72 20 74 6f 20 61 20 66 69 6c 65 6e 61 6d 65  er to a filename
34f00 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
34f10 69 74 68 20 64 61 74 61 62 61 73 65 20 4e 20 6f  ith database N o
34f20 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  f connection D. 
34f30 20 5e 54 68 65 20 6d 61 69 6e 20 64 61 74 61 62   ^The main datab
34f40 61 73 65 20 66 69 6c 65 0a 2a 2a 20 68 61 73 20  ase file.** has 
34f50 74 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 2e  the name "main".
34f60 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
34f70 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
34f80 73 65 20 4e 20 6f 6e 20 74 68 65 20 64 61 74 61  se N on the data
34f90 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
34fa0 6f 6e 20 44 2c 20 6f 72 20 69 66 20 64 61 74 61  on D, or if data
34fb0 62 61 73 65 20 4e 20 69 73 20 61 20 74 65 6d 70  base N is a temp
34fc0 6f 72 61 72 79 20 6f 72 20 69 6e 2d 6d 65 6d 6f  orary or in-memo
34fd0 72 79 20 64 61 74 61 62 61 73 65 2c 20 74 68 65  ry database, the
34fe0 6e 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n.** a NULL poin
34ff0 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
35000 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 6c 65  .**.** ^The file
35010 6e 61 6d 65 20 72 65 74 75 72 6e 65 64 20 62 79  name returned by
35020 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   this function i
35030 73 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20  s the output of 
35040 74 68 65 0a 2a 2a 20 78 46 75 6c 6c 50 61 74 68  the.** xFullPath
35050 6e 61 6d 65 20 6d 65 74 68 6f 64 20 6f 66 20 74  name method of t
35060 68 65 20 5b 56 46 53 5d 2e 20 20 5e 49 6e 20 6f  he [VFS].  ^In o
35070 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
35080 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  filename.** will
35090 20 62 65 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   be an absolute 
350a0 70 61 74 68 6e 61 6d 65 2c 20 65 76 65 6e 20 69  pathname, even i
350b0 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 75  f the filename u
350c0 73 65 64 0a 2a 2a 20 74 6f 20 6f 70 65 6e 20 74  sed.** to open t
350d0 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 69 67  he database orig
350e0 69 6e 61 6c 6c 79 20 77 61 73 20 61 20 55 52 49  inally was a URI
350f0 20 6f 72 20 72 65 6c 61 74 69 76 65 20 70 61 74   or relative pat
35100 68 6e 61 6d 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  hname..*/.const 
35110 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64 62  char *sqlite3_db
35120 5f 66 69 6c 65 6e 61 6d 65 28 73 71 6c 69 74 65  _filename(sqlite
35130 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 61  3 *db, const cha
35140 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a  r *zDbName);../*
35150 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
35160 74 65 72 6d 69 6e 65 20 69 66 20 61 20 64 61 74  termine if a dat
35170 61 62 61 73 65 20 69 73 20 72 65 61 64 2d 6f 6e  abase is read-on
35180 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ly.**.** ^The sq
35190 6c 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c  lite3_db_readonl
351a0 79 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  y(D,N) interface
351b0 20 72 65 74 75 72 6e 73 20 31 20 69 66 20 74 68   returns 1 if th
351c0 65 20 64 61 74 61 62 61 73 65 20 4e 0a 2a 2a 20  e database N.** 
351d0 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 20  of connection D 
351e0 69 73 20 72 65 61 64 2d 6f 6e 6c 79 2c 20 30 20  is read-only, 0 
351f0 69 66 20 69 74 20 69 73 20 72 65 61 64 2f 77 72  if it is read/wr
35200 69 74 65 2c 20 6f 72 20 2d 31 20 69 66 20 4e 20  ite, or -1 if N 
35210 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 6e 61  is not.** the na
35220 6d 65 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  me of a database
35230 20 6f 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44   on connection D
35240 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
35250 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c  _db_readonly(sql
35260 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20  ite3 *db, const 
35270 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a  char *zDbName);.
35280 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35290 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70   Find the next p
352a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
352b0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  t.**.** ^This in
352c0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
352d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
352e0 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20   next [prepared 
352f0 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72  statement] after
35300 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69  .** pStmt associ
35310 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
35320 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35330 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53  on] pDb.  ^If pS
35340 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74  tmt is NULL.** t
35350 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61  hen this interfa
35360 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
35370 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 73  nter to the firs
35380 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
35390 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74  ment.** associat
353a0 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74 61  ed with the data
353b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
353c0 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65  pDb.  ^If no pre
353d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
353e0 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65  ** satisfies the
353f0 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74   conditions of t
35400 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20  his routine, it 
35410 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a  returns NULL..**
35420 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73  .** The [databas
35430 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f  e connection] po
35440 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c  inter D in a cal
35450 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
35460 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d  _next_stmt(D,S)]
35470 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20 61   must refer to a
35480 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a  n open database.
35490 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e  ** connection an
354a0 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20  d in particular 
354b0 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55  must not be a NU
354c0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73  LL pointer..*/.s
354d0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c  qlite3_stmt *sql
354e0 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73  ite3_next_stmt(s
354f0 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c  qlite3 *pDb, sql
35500 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
35510 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
35520 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52  EF: Commit And R
35530 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61  ollback Notifica
35540 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
35550 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35560 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20  3_commit_hook() 
35570 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
35580 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
35590 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
355a0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
355b0 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
355c0 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d  is [COMMIT | com
355d0 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79  mitted]..** ^Any
355e0 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
355f0 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
35600 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
35610 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
35620 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
35630 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
35640 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
35650 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c  ^The sqlite3_rol
35660 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74  lback_hook() int
35670 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
35680 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
35690 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
356a0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
356b0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
356c0 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c  [ROLLBACK | roll
356d0 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e  ed back]..** ^An
356e0 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
356f0 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
35700 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c  l to sqlite3_rol
35710 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  lback_hook().** 
35720 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
35730 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35740 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
35750 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72 67  ** ^The pArg arg
35760 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20  ument is passed 
35770 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63  through to the c
35780 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20  allback..** ^If 
35790 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20  the callback on 
357a0 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75  a commit hook fu
357b0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e  nction returns n
357c0 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e  on-zero,.** then
357d0 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63   the commit is c
357e0 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
357f0 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
35800 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
35810 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20  mit_hook(D,C,P) 
35820 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  and sqlite3_roll
35830 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  back_hook(D,C,P)
35840 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65   functions.** re
35850 74 75 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d  turn the P argum
35860 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65  ent from the pre
35870 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68  vious call of th
35880 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a  e same function.
35890 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ** on the same [
358a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
358b0 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20  ion] D, or NULL 
358c0 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74  for.** the first
358d0 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66   call for each f
358e0 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a  unction on D..**
358f0 0a 2a 2a 20 54 68 65 20 63 6f 6d 6d 69 74 20 61  .** The commit a
35900 6e 64 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b  nd rollback hook
35910 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6e   callbacks are n
35920 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 0a 2a 2a  ot reentrant..**
35930 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d   The callback im
35940 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
35950 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
35960 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
35970 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
35980 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
35990 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63  at invoked the c
359a0 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63  allback.  Any ac
359b0 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69  tions.** to modi
359c0 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
359d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
359e0 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69  be deferred unti
359f0 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63  l after the.** c
35a00 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65  ompletion of the
35a10 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
35a20 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  ] call that trig
35a30 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74  gered the commit
35a40 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  .** or rollback 
35a50 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73  hook in the firs
35a60 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65  t place..** Note
35a70 20 74 68 61 74 20 72 75 6e 6e 69 6e 67 20 61 6e   that running an
35a80 79 20 6f 74 68 65 72 20 53 51 4c 20 73 74 61 74  y other SQL stat
35a90 65 6d 65 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e  ements, includin
35aa0 67 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  g SELECT stateme
35ab0 6e 74 73 2c 0a 2a 2a 20 6f 72 20 6d 65 72 65 6c  nts,.** or merel
35ac0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
35ad0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
35ae0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
35af0 65 70 28 29 5d 20 77 69 6c 6c 20 6d 6f 64 69 66  ep()] will modif
35b00 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
35b10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
35b20 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
35b30 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
35b40 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
35b50 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20  ** ^Registering 
35b60 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20  a NULL function 
35b70 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c  disables the cal
35b80 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  lback..**.** ^Wh
35b90 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f  en the commit ho
35ba0 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  ok callback rout
35bb0 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ine returns zero
35bc0 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a  , the [COMMIT].*
35bd0 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  * operation is a
35be0 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e  llowed to contin
35bf0 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49  ue normally.  ^I
35c00 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f  f the commit hoo
35c10 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e  k.** returns non
35c20 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
35c30 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76  [COMMIT] is conv
35c40 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f  erted into a [RO
35c50 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65  LLBACK]..** ^The
35c60 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69   rollback hook i
35c70 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72  s invoked on a r
35c80 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73  ollback that res
35c90 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d  ults from a comm
35ca0 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72  it.** hook retur
35cb0 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a  ning non-zero, j
35cc0 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20  ust as it would 
35cd0 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65  be with any othe
35ce0 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  r rollback..**.*
35cf0 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
35d00 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c  ses of this API,
35d10 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
35d20 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62  s said to have b
35d30 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61  een.** rolled ba
35d40 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69  ck if an explici
35d50 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61  t "ROLLBACK" sta
35d60 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74  tement is execut
35d70 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72  ed, or.** an err
35d80 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74  or or constraint
35d90 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69   causes an impli
35da0 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20  cit rollback to 
35db0 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72  occur..** ^The r
35dc0 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b  ollback callback
35dd0 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
35de0 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  if a transaction
35df0 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   is.** automatic
35e00 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
35e10 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74   because the dat
35e20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35e30 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
35e40 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
35e50 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
35e60 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ook()] interface
35e70 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
35e80 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73  e3_commit_hook(s
35e90 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
35ea0 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
35eb0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f  void *sqlite3_ro
35ec0 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69  llback_hook(sqli
35ed0 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f  te3*, void(*)(vo
35ee0 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  id *), void*);..
35ef0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
35f00 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69  Data Change Noti
35f10 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
35f20 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ks.**.** ^The sq
35f30 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
35f40 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
35f50 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
35f60 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  ck function.** w
35f70 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
35f80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64  e connection] id
35f90 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
35fa0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a  first argument.*
35fb0 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  * to be invoked 
35fc0 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69  whenever a row i
35fd0 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
35fe0 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
35ff0 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b  ** ^Any callback
36000 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
36010 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  us call to this 
36020 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20  function.** for 
36030 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
36040 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
36050 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a  overridden..**.*
36060 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  * ^The second ar
36070 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
36080 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74  ter to the funct
36090 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68  ion to invoke wh
360a0 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75  en a.** row is u
360b0 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64  pdated, inserted
360c0 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20   or deleted..** 
360d0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
360e0 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ent to the callb
360f0 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
36100 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
36110 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ent.** to sqlite
36120 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e  3_update_hook().
36130 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
36140 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e  callback argumen
36150 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
36160 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51  ITE_INSERT], [SQ
36170 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a  LITE_DELETE],.**
36180 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41   or [SQLITE_UPDA
36190 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  TE], depending o
361a0 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  n the operation 
361b0 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20  that caused the 
361c0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62  callback.** to b
361d0 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54  e invoked..** ^T
361e0 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
361f0 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  rth arguments to
36200 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f   the callback co
36210 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74  ntain pointers t
36220 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
36230 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65  e and table name
36240 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
36250 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a  affected row..**
36260 20 5e 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c   ^The final call
36270 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  back parameter i
36280 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
36290 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e   the row..** ^In
362a0 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20   the case of an 
362b0 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20  update, this is 
362c0 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65  the [rowid] afte
362d0 72 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b  r the update tak
362e0 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  es place..**.** 
362f0 5e 28 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f  ^(The update hoo
36300 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
36310 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73   when internal s
36320 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65  ystem tables are
36330 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e  .** modified (i.
36340 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72  e. sqlite_master
36350 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75   and sqlite_sequ
36360 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ence).)^.**.** ^
36370 49 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  In the current i
36380 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74  mplementation, t
36390 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a  he update hook.*
363a0 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  * is not invoked
363b0 20 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f   when duplicatio
363c0 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  n rows are delet
363d0 65 64 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e  ed because of an
363e0 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54  .** [ON CONFLICT
363f0 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52   | ON CONFLICT R
36400 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20  EPLACE] clause. 
36410 20 5e 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64   ^Nor is the upd
36420 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f  ate hook.** invo
36430 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72  ked when rows ar
36440 65 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20  e deleted using 
36450 74 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  the [truncate op
36460 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20  timization]..** 
36470 54 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64  The exceptions d
36480 65 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70  efined in this p
36490 61 72 61 67 72 61 70 68 20 6d 69 67 68 74 20 63  aragraph might c
364a0 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
364b0 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
364c0 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
364d0 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d  e update hook im
364e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
364f0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
36500 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
36510 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
36520 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
36530 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75  at invoked the u
36540 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79  pdate hook.  Any
36550 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d   actions.** to m
36560 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
36570 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
36580 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75  st be deferred u
36590 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a  ntil after the.*
365a0 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20  * completion of 
365b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
365c0 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74  p()] call that t
365d0 72 69 67 67 65 72 65 64 20 74 68 65 20 75 70 64  riggered the upd
365e0 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74  ate hook..** Not
365f0 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
36600 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
36610 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
36620 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
36630 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
36640 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
36650 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
36660 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
36670 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
36680 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75  * ^The sqlite3_u
36690 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50  pdate_hook(D,C,P
366a0 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65  ) function.** re
366b0 74 75 72 6e 73 20 74 68 65 20 50 20 61 72 67 75  turns the P argu
366c0 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72  ment from the pr
366d0 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f  evious call.** o
366e0 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
366f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
36700 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a   D, or NULL for.
36710 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  ** the first cal
36720 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65  l on D..**.** Se
36730 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
36740 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
36750 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
36760 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d  rollback_hook()]
36770 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  .** interfaces..
36780 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
36790 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20  _update_hook(.  
367a0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
367b0 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20  d(*)(void *,int 
367c0 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68  ,char const *,ch
367d0 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74  ar const *,sqlit
367e0 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69  e3_int64),.  voi
367f0 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  d*.);../*.** CAP
36800 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
36810 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20   Disable Shared 
36820 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 20 4b  Pager Cache.** K
36830 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64  EYWORDS: {shared
36840 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28   cache}.**.** ^(
36850 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61  This routine ena
36860 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
36870 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20   the sharing of 
36880 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61 63  the database cac
36890 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61  he.** and schema
368a0 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
368b0 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61   between [databa
368c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20  se connection | 
368d0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20  connections].** 
368e0 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  to the same data
368f0 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73  base. Sharing is
36900 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
36910 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65  argument is true
36920 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64  .** and disabled
36930 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   if the argument
36940 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a   is false.)^.**.
36950 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69 6e  ** ^Cache sharin
36960 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64  g is enabled and
36970 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e   disabled for an
36980 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e   entire process.
36990 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68  .** This is a ch
369a0 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74  ange as of SQLit
369b0 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e  e version 3.5.0.
369c0 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f   In prior versio
369d0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a  ns of SQLite,.**
369e0 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61   sharing was ena
369f0 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
36a00 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64   for each thread
36a10 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
36a20 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20 73  ** ^(The cache s
36a30 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20  haring mode set 
36a40 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  by this interfac
36a50 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75  e effects all su
36a60 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
36a70 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  s to [sqlite3_op
36a80 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
36a90 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20  open_v2()], and 
36aa0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
36ab0 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  )]..** Existing 
36ac0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36ad0 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73  ions continue us
36ae0 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f  e the sharing mo
36af0 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69  de.** that was i
36b00 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20  n effect at the 
36b10 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f  time they were o
36b20 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  pened.)^.**.** ^
36b30 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  (This routine re
36b40 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
36b50 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68  ] if shared cach
36b60 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72  e was enabled or
36b70 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63   disabled.** suc
36b80 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b  cessfully.  An [
36b90 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
36ba0 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73  eturned otherwis
36bb0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72  e.)^.**.** ^Shar
36bc0 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61  ed cache is disa
36bd0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
36be0 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74 20   But this might 
36bf0 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74  change in.** fut
36c00 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
36c10 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61  SQLite.  Applica
36c20 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20  tions that care 
36c30 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20  about shared.** 
36c40 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73 68  cache setting sh
36c50 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c  ould set it expl
36c60 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65  icitly..**.** Se
36c70 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65  e Also:  [SQLite
36c80 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f   Shared-Cache Mo
36c90 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  de].*/.int sqlit
36ca0 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
36cb0 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a  _cache(int);../*
36cc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74  .** CAPI3REF: At
36cd0 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65  tempt To Free He
36ce0 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20  ap Memory.**.** 
36cf0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c  ^The sqlite3_rel
36d00 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e  ease_memory() in
36d10 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
36d20 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73   to free N bytes
36d30 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f  .** of heap memo
36d40 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69  ry by deallocati
36d50 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c  ng non-essential
36d60 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
36d70 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74  ons.** held by t
36d80 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72  he database libr
36d90 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73  ary.   Memory us
36da0 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 61  ed to cache data
36db0 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f  base.** pages to
36dc0 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d   improve perform
36dd0 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70  ance is an examp
36de0 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74  le of non-essent
36df0 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ial memory..** ^
36e00 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
36e10 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73  memory() returns
36e20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
36e30 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72  ytes actually fr
36e40 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69  eed,.** which mi
36e50 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c  ght be more or l
36e60 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f  ess than the amo
36e70 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a  unt requested..*
36e80 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
36e90 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20  elease_memory() 
36ea0 72 6f 75 74 69 6e 65 20 69 73 20 61 20 6e 6f 2d  routine is a no-
36eb0 6f 70 20 72 65 74 75 72 6e 69 6e 67 20 7a 65 72  op returning zer
36ec0 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69  o.** if SQLite i
36ed0 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65 64 20 77  s not compiled w
36ee0 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  ith [SQLITE_ENAB
36ef0 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45  LE_MEMORY_MANAGE
36f00 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  MENT]..**.** See
36f10 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
36f20 64 62 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  db_release_memor
36f30 79 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  y()].*/.int sqli
36f40 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
36f50 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ry(int);../*.** 
36f60 43 41 50 49 33 52 45 46 3a 20 46 72 65 65 20 4d  CAPI3REF: Free M
36f70 65 6d 6f 72 79 20 55 73 65 64 20 42 79 20 41 20  emory Used By A 
36f80 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
36f90 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
36fa0 71 6c 69 74 65 33 5f 64 62 5f 72 65 6c 65 61 73  qlite3_db_releas
36fb0 65 5f 6d 65 6d 6f 72 79 28 44 29 20 69 6e 74 65  e_memory(D) inte
36fc0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
36fd0 6f 20 66 72 65 65 20 61 73 20 6d 75 63 68 20 68  o free as much h
36fe0 65 61 70 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 73  eap.** memory as
36ff0 20 70 6f 73 73 69 62 6c 65 20 66 72 6f 6d 20 64   possible from d
37000 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37010 6f 6e 20 44 2e 20 55 6e 6c 69 6b 65 20 74 68 65  on D. Unlike the
37020 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c  .** [sqlite3_rel
37030 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69  ease_memory()] i
37040 6e 74 65 72 66 61 63 65 2c 20 74 68 69 73 20 69  nterface, this i
37050 6e 74 65 72 66 61 63 65 20 69 73 20 65 66 66 65  nterface is effe
37060 63 74 20 65 76 65 6e 0a 2a 2a 20 77 68 65 6e 20  ct even.** when 
37070 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 45 4e 41  then [SQLITE_ENA
37080 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47  BLE_MEMORY_MANAG
37090 45 4d 45 4e 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  EMENT] compile-t
370a0 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ime option is.**
370b0 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   omitted..**.** 
370c0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
370d0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
370e0 79 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  y()].*/.int sqli
370f0 74 65 33 5f 64 62 5f 72 65 6c 65 61 73 65 5f 6d  te3_db_release_m
37100 65 6d 6f 72 79 28 73 71 6c 69 74 65 33 2a 29 3b  emory(sqlite3*);
37110 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37120 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74  : Impose A Limit
37130 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a   On Heap Size.**
37140 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37150 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
37160 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  64() interface s
37170 65 74 73 20 61 6e 64 2f 6f 72 20 71 75 65 72 69  ets and/or queri
37180 65 73 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 6c  es the.** soft l
37190 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75  imit on the amou
371a0 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  nt of heap memor
371b0 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c  y that may be al
371c0 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
371d0 65 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 73 74  e..** ^SQLite st
371e0 72 69 76 65 73 20 74 6f 20 6b 65 65 70 20 68 65  rives to keep he
371f0 61 70 20 6d 65 6d 6f 72 79 20 75 74 69 6c 69 7a  ap memory utiliz
37200 61 74 69 6f 6e 20 62 65 6c 6f 77 20 74 68 65 20  ation below the 
37210 73 6f 66 74 20 68 65 61 70 0a 2a 2a 20 6c 69 6d  soft heap.** lim
37220 69 74 20 62 79 20 72 65 64 75 63 69 6e 67 20 74  it by reducing t
37230 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
37240 65 73 20 68 65 6c 64 20 69 6e 20 74 68 65 20 70  es held in the p
37250 61 67 65 20 63 61 63 68 65 0a 2a 2a 20 61 73 20  age cache.** as 
37260 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 73 61 67  heap memory usag
37270 65 73 20 61 70 70 72 6f 61 63 68 65 73 20 74 68  es approaches th
37280 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65  e limit..** ^The
37290 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
372a0 20 69 73 20 22 73 6f 66 74 22 20 62 65 63 61 75   is "soft" becau
372b0 73 65 20 65 76 65 6e 20 74 68 6f 75 67 68 20 53  se even though S
372c0 51 4c 69 74 65 20 73 74 72 69 76 65 73 20 74 6f  QLite strives to
372d0 20 73 74 61 79 0a 2a 2a 20 62 65 6c 6f 77 20 74   stay.** below t
372e0 68 65 20 6c 69 6d 69 74 2c 20 69 74 20 77 69 6c  he limit, it wil
372f0 6c 20 65 78 63 65 65 64 20 74 68 65 20 6c 69 6d  l exceed the lim
37300 69 74 20 72 61 74 68 65 72 20 74 68 61 6e 20 67  it rather than g
37310 65 6e 65 72 61 74 65 0a 2a 2a 20 61 6e 20 5b 53  enerate.** an [S
37320 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 65 72 72  QLITE_NOMEM] err
37330 6f 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  or.  In other wo
37340 72 64 73 2c 20 74 68 65 20 73 6f 66 74 20 68 65  rds, the soft he
37350 61 70 20 6c 69 6d 69 74 20 0a 2a 2a 20 69 73 20  ap limit .** is 
37360 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a  advisory only..*
37370 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  *.** ^The return
37380 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
37390 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
373a0 6d 69 74 36 34 28 29 20 69 73 20 74 68 65 20 73  mit64() is the s
373b0 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20 73 6f  ize of.** the so
373c0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 70 72  ft heap limit pr
373d0 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 2c  ior to the call,
373e0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 69 6e 20   or negative in 
373f0 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 0a 2a  the case of an.*
37400 2a 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68  * error.  ^If th
37410 65 20 61 72 67 75 6d 65 6e 74 20 4e 20 69 73 20  e argument N is 
37420 6e 65 67 61 74 69 76 65 0a 2a 2a 20 74 68 65 6e  negative.** then
37430 20 6e 6f 20 63 68 61 6e 67 65 20 69 73 20 6d 61   no change is ma
37440 64 65 20 74 6f 20 74 68 65 20 73 6f 66 74 20 68  de to the soft h
37450 65 61 70 20 6c 69 6d 69 74 2e 20 20 48 65 6e 63  eap limit.  Henc
37460 65 2c 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  e, the current.*
37470 2a 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 6f  * size of the so
37480 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61  ft heap limit ca
37490 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
374a0 62 79 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  by invoking.** s
374b0 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
374c0 5f 6c 69 6d 69 74 36 34 28 29 20 77 69 74 68 20  _limit64() with 
374d0 61 20 6e 65 67 61 74 69 76 65 20 61 72 67 75 6d  a negative argum
374e0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ent..**.** ^If t
374f0 68 65 20 61 72 67 75 6d 65 6e 74 20 4e 20 69 73  he argument N is
37500 20 7a 65 72 6f 20 74 68 65 6e 20 74 68 65 20 73   zero then the s
37510 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
37520 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  s disabled..**.*
37530 2a 20 5e 28 54 68 65 20 73 6f 66 74 20 68 65 61  * ^(The soft hea
37540 70 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 65  p limit is not e
37550 6e 66 6f 72 63 65 64 20 69 6e 20 74 68 65 20 63  nforced in the c
37560 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
37570 61 74 69 6f 6e 0a 2a 2a 20 69 66 20 6f 6e 65 20  ation.** if one 
37580 6f 72 20 6d 6f 72 65 20 6f 66 20 66 6f 6c 6c 6f  or more of follo
37590 77 69 6e 67 20 63 6f 6e 64 69 74 69 6f 6e 73 20  wing conditions 
375a0 61 72 65 20 74 72 75 65 3a 0a 2a 2a 0a 2a 2a 20  are true:.**.** 
375b0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
375c0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
375d0 20 69 73 20 73 65 74 20 74 6f 20 7a 65 72 6f 2e   is set to zero.
375e0 0a 2a 2a 20 3c 6c 69 3e 20 4d 65 6d 6f 72 79 20  .** <li> Memory 
375f0 61 63 63 6f 75 6e 74 69 6e 67 20 69 73 20 64 69  accounting is di
37600 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63  sabled using a c
37610 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68  ombination of th
37620 65 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74  e.**      [sqlit
37630 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
37640 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
37650 54 55 53 5d 2c 2e 2e 2e 29 20 73 74 61 72 74 2d  TUS],...) start-
37660 74 69 6d 65 20 6f 70 74 69 6f 6e 20 61 6e 64 0a  time option and.
37670 2a 2a 20 20 20 20 20 20 74 68 65 20 5b 53 51 4c  **      the [SQL
37680 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53  ITE_DEFAULT_MEMS
37690 54 41 54 55 53 5d 20 63 6f 6d 70 69 6c 65 2d 74  TATUS] compile-t
376a0 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c  ime option..** <
376b0 6c 69 3e 20 41 6e 20 61 6c 74 65 72 6e 61 74 69  li> An alternati
376c0 76 65 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  ve page cache im
376d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
376e0 73 70 65 63 69 66 69 65 64 20 75 73 69 6e 67 0a  specified using.
376f0 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33  **      [sqlite3
37700 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
37710 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
37720 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  ,...)..** <li> T
37730 68 65 20 70 61 67 65 20 63 61 63 68 65 20 61 6c  he page cache al
37740 6c 6f 63 61 74 65 73 20 66 72 6f 6d 20 69 74 73  locates from its
37750 20 6f 77 6e 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c   own memory pool
37760 20 73 75 70 70 6c 69 65 64 0a 2a 2a 20 20 20 20   supplied.**    
37770 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f    by [sqlite3_co
37780 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
37790 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2c  NFIG_PAGECACHE],
377a0 2e 2e 2e 29 20 72 61 74 68 65 72 20 74 68 61 6e  ...) rather than
377b0 0a 2a 2a 20 20 20 20 20 20 66 72 6f 6d 20 74 68  .**      from th
377c0 65 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f 75 6c 3e  e heap..** </ul>
377d0 29 5e 0a 2a 2a 0a 2a 2a 20 42 65 67 69 6e 6e 69  )^.**.** Beginni
377e0 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 76  ng with SQLite v
377f0 65 72 73 69 6f 6e 20 33 2e 37 2e 33 2c 20 74 68  ersion 3.7.3, th
37800 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
37810 74 20 69 73 20 65 6e 66 6f 72 63 65 64 0a 2a 2a  t is enforced.**
37820 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
37830 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
37840 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  e [SQLITE_ENABLE
37850 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45  _MEMORY_MANAGEME
37860 4e 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  NT].** compile-t
37870 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e  ime option is in
37880 76 6f 6b 65 64 2e 20 20 57 69 74 68 20 5b 53 51  voked.  With [SQ
37890 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f  LITE_ENABLE_MEMO
378a0 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 0a  RY_MANAGEMENT],.
378b0 2a 2a 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  ** the soft heap
378c0 20 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63   limit is enforc
378d0 65 64 20 6f 6e 20 65 76 65 72 79 20 6d 65 6d 6f  ed on every memo
378e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20  ry allocation.  
378f0 57 69 74 68 6f 75 74 0a 2a 2a 20 5b 53 51 4c 49  Without.** [SQLI
37900 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59  TE_ENABLE_MEMORY
37910 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 20 74 68  _MANAGEMENT], th
37920 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
37930 74 20 69 73 20 6f 6e 6c 79 20 65 6e 66 6f 72 63  t is only enforc
37940 65 64 0a 2a 2a 20 77 68 65 6e 20 6d 65 6d 6f 72  ed.** when memor
37950 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 62  y is allocated b
37960 79 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65  y the page cache
37970 2e 20 20 54 65 73 74 69 6e 67 20 73 75 67 67 65  .  Testing sugge
37980 73 74 73 20 74 68 61 74 20 62 65 63 61 75 73 65  sts that because
37990 0a 2a 2a 20 74 68 65 20 70 61 67 65 20 63 61 63  .** the page cac
379a0 68 65 20 69 73 20 74 68 65 20 70 72 65 64 6f 6d  he is the predom
379b0 69 6e 61 74 65 20 6d 65 6d 6f 72 79 20 75 73 65  inate memory use
379c0 72 20 69 6e 20 53 51 4c 69 74 65 2c 20 6d 6f 73  r in SQLite, mos
379d0 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
379e0 73 20 77 69 6c 6c 20 61 63 68 69 65 76 65 20 61  s will achieve a
379f0 64 65 71 75 61 74 65 20 73 6f 66 74 20 68 65 61  dequate soft hea
37a00 70 20 6c 69 6d 69 74 20 65 6e 66 6f 72 63 65 6d  p limit enforcem
37a10 65 6e 74 20 77 69 74 68 6f 75 74 0a 2a 2a 20 74  ent without.** t
37a20 68 65 20 75 73 65 20 6f 66 20 5b 53 51 4c 49 54  he use of [SQLIT
37a30 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f  E_ENABLE_MEMORY_
37a40 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a  MANAGEMENT]..**.
37a50 2a 2a 20 54 68 65 20 63 69 72 63 75 6d 73 74 61  ** The circumsta
37a60 6e 63 65 73 20 75 6e 64 65 72 20 77 68 69 63 68  nces under which
37a70 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 6e 66   SQLite will enf
37a80 6f 72 63 65 20 74 68 65 20 73 6f 66 74 20 68 65  orce the soft he
37a90 61 70 20 6c 69 6d 69 74 20 6d 61 79 0a 2a 2a 20  ap limit may.** 
37aa0 63 68 61 6e 67 65 73 20 69 6e 20 66 75 74 75 72  changes in futur
37ab0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
37ac0 4c 69 74 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  Lite..*/.sqlite3
37ad0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 73  _int64 sqlite3_s
37ae0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
37af0 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 4e  (sqlite3_int64 N
37b00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37b10 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 53  EF: Deprecated S
37b20 6f 66 74 20 48 65 61 70 20 4c 69 6d 69 74 20 49  oft Heap Limit I
37b30 6e 74 65 72 66 61 63 65 0a 2a 2a 20 44 45 50 52  nterface.** DEPR
37b40 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 69  ECATED.**.** Thi
37b50 73 20 69 73 20 61 20 64 65 70 72 65 63 61 74 65  s is a deprecate
37b60 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  d version of the
37b70 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
37b80 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a  eap_limit64()].*
37b90 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  * interface.  Th
37ba0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 70 72  is routine is pr
37bb0 6f 76 69 64 65 64 20 66 6f 72 20 68 69 73 74 6f  ovided for histo
37bc0 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c  rical compatibil
37bd0 69 74 79 0a 2a 2a 20 6f 6e 6c 79 2e 20 20 41 6c  ity.** only.  Al
37be0 6c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  l new applicatio
37bf0 6e 73 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  ns should use th
37c00 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6f  e.** [sqlite3_so
37c10 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
37c20 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 61 74  )] interface rat
37c30 68 65 72 20 74 68 61 6e 20 74 68 69 73 20 6f 6e  her than this on
37c40 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50  e..*/.SQLITE_DEP
37c50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c  RECATED void sql
37c60 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
37c70 69 6d 69 74 28 69 6e 74 20 4e 29 3b 0a 0a 0a 2f  imit(int N);.../
37c80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
37c90 78 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20  xtract Metadata 
37ca0 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f  About A Column O
37cb0 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20  f A Table.**.** 
37cc0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
37cd0 74 75 72 6e 73 20 6d 65 74 61 64 61 74 61 20 61  turns metadata a
37ce0 62 6f 75 74 20 61 20 73 70 65 63 69 66 69 63 20  bout a specific 
37cf0 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63  column of a spec
37d00 69 66 69 63 0a 2a 2a 20 64 61 74 61 62 61 73 65  ific.** database
37d10 20 74 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c   table accessibl
37d20 65 20 75 73 69 6e 67 20 74 68 65 20 5b 64 61 74  e using the [dat
37d30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37d40 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73  ] handle.** pass
37d50 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
37d60 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
37d70 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f  t..**.** ^The co
37d80 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69  lumn is identifi
37d90 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
37da0 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  , third and four
37db0 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
37dc0 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f  .** this functio
37dd0 6e 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  n. ^The second p
37de0 61 72 61 6d 65 74 65 72 20 69 73 20 65 69 74 68  arameter is eith
37df0 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  er the name of t
37e00 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28  he database.** (
37e10 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65  i.e. "main", "te
37e20 6d 70 22 2c 20 6f 72 20 61 6e 20 61 74 74 61 63  mp", or an attac
37e30 68 65 64 20 64 61 74 61 62 61 73 65 29 20 63 6f  hed database) co
37e40 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65  ntaining the spe
37e50 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20  cified.** table 
37e60 6f 72 20 4e 55 4c 4c 2e 20 5e 49 66 20 69 74 20  or NULL. ^If it 
37e70 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c  is NULL, then al
37e80 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  l attached datab
37e90 61 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65  ases are searche
37ea0 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62  d.** for the tab
37eb0 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  le using the sam
37ec0 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64  e algorithm used
37ed0 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65   by the database
37ee0 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65   engine to.** re
37ef0 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65  solve unqualifie
37f00 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63  d table referenc
37f10 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  es..**.** ^The t
37f20 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
37f30 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
37f40 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  is function are 
37f50 74 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f  the table and co
37f60 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20  lumn.** name of 
37f70 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75  the desired colu
37f80 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  mn, respectively
37f90 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65  . Neither of the
37fa0 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  se parameters.**
37fb0 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   may be NULL..**
37fc0 0a 2a 2a 20 5e 4d 65 74 61 64 61 74 61 20 69 73  .** ^Metadata is
37fd0 20 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69   returned by wri
37fe0 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f  ting to the memo
37ff0 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73  ry locations pas
38000 73 65 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a  sed as the 5th.*
38010 2a 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  * and subsequent
38020 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
38030 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 41  his function. ^A
38040 6e 79 20 6f 66 20 74 68 65 73 65 20 61 72 67 75  ny of these argu
38050 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20  ments may be.** 
38060 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63  NULL, in which c
38070 61 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ase the correspo
38080 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66  nding element of
38090 20 6d 65 74 61 64 61 74 61 20 69 73 20 6f 6d 69   metadata is omi
380a0 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62  tted..**.** ^(<b
380b0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
380c0 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
380d0 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72  .** <tr><th> Par
380e0 61 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75 74 70  ameter <th> Outp
380f0 75 74 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ut<br>Type <th> 
38100 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a   Description.**.
38110 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20  ** <tr><td> 5th 
38120 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a  <td> const char*
38130 20 3c 74 64 3e 20 44 61 74 61 20 74 79 70 65 0a   <td> Data type.
38140 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20  ** <tr><td> 6th 
38150 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a  <td> const char*
38160 20 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65   <td> Name of de
38170 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20  fault collation 
38180 73 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e  sequence.** <tr>
38190 3c 74 64 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e  <td> 7th <td> in
381a0 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54  t         <td> T
381b0 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61  rue if column ha
381c0 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e  s a NOT NULL con
381d0 73 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c  straint.** <tr><
381e0 74 64 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e 74  td> 8th <td> int
381f0 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72           <td> Tr
38200 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20  ue if column is 
38210 70 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d  part of the PRIM
38220 41 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c  ARY KEY.** <tr><
38230 74 64 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e 74  td> 9th <td> int
38240 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72           <td> Tr
38250 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20  ue if column is 
38260 5b 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a  [AUTOINCREMENT].
38270 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
38280 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
38290 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
382a0 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
382b0 68 65 20 63 68 61 72 61 63 74 65 72 20 70 6f 69  he character poi
382c0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 66  nters returned f
382d0 6f 72 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61 72  or the.** declar
382e0 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63  ation type and c
382f0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
38300 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20  e is valid only 
38310 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a  until the next.*
38320 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51  * call to any SQ
38330 4c 69 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f  Lite API functio
38340 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  n..**.** ^If the
38350 20 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65   specified table
38360 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76   is actually a v
38370 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63  iew, an [error c
38380 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
38390 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
383a0 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e  specified column
383b0 20 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69   is "rowid", "oi
383c0 64 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20  d" or "_rowid_" 
383d0 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47  and an.** [INTEG
383e0 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
383f0 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20  column has been 
38400 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
38410 72 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75  red, then the ou
38420 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  tput.** paramete
38430 72 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74  rs are set for t
38440 68 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  he explicitly de
38450 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 5e  clared column. ^
38460 28 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a  (If there is no.
38470 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  ** explicitly de
38480 63 6c 61 72 65 64 20 5b 49 4e 54 45 47 45 52 20  clared [INTEGER 
38490 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c  PRIMARY KEY] col
384a0 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75  umn, then the ou
384b0 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  tput.** paramete
384c0 72 73 20 61 72 65 20 73 65 74 20 61 73 20 66 6f  rs are set as fo
384d0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72  llows:.**.** <pr
384e0 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74  e>.**     data t
384f0 79 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a  ype: "INTEGER".*
38500 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20  *     collation 
38510 73 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52  sequence: "BINAR
38520 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75  Y".**     not nu
38530 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69  ll: 0.**     pri
38540 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20  mary key: 1.**  
38550 20 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e     auto incremen
38560 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e  t: 0.** </pre>)^
38570 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75  .**.** ^(This fu
38580 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20  nction may load 
38590 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65  one or more sche
385a0 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73  mas from databas
385b0 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a  e files. If an.*
385c0 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  * error occurs d
385d0 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65  uring this proce
385e0 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65  ss, or if the re
385f0 71 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72  quested table or
38600 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f   column.** canno
38610 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b  t be found, an [
38620 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
38630 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65  eturned and an e
38640 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66  rror message lef
38650 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74  t.** in the [dat
38660 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
38670 5d 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76  ] (to be retriev
38680 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  ed using sqlite3
38690 5f 65 72 72 6d 73 67 28 29 29 2e 29 5e 0a 2a 2a  _errmsg()).)^.**
386a0 0a 2a 2a 20 5e 54 68 69 73 20 41 50 49 20 69 73  .** ^This API is
386b0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
386c0 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
386d0 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
386e0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
386f0 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
38700 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
38710 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65  cessor symbol de
38720 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  fined..*/.int sq
38730 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75  lite3_table_colu
38740 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73  mn_metadata(.  s
38750 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
38760 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
38770 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20  nnection handle 
38780 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
38790 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20  *zDbName,       
387a0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d   /* Database nam
387b0 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63  e or NULL */.  c
387c0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c  onst char *zTabl
387d0 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61  eName,     /* Ta
387e0 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f  ble name */.  co
387f0 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d  nst char *zColum
38800 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c  nName,    /* Col
38810 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68  umn name */.  ch
38820 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74  ar const **pzDat
38830 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54  aType,    /* OUT
38840 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61  PUT: Declared da
38850 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61  ta type */.  cha
38860 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c  r const **pzColl
38870 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50  Seq,     /* OUTP